smart_websocket_client v0.1.0 SmartWebsocketClient

SmartWebsocketClient is a (not-so) smart websocket client with pool support.

The main goal of this library is to provide a simple interface to send and receive websocket messages. Have in mind that this is only a client, if you want a server take a look at Cowboy. There is a simple implementation of a websocket server at test/helper/server.ex, which is a helper to test the client.

The client will spawn two processes for each socket. One is responsible for saving the socket state in a pool, and the other listens for new messages.

Pool

SWC adds support for pools through poolboy (hopefully a twink?). If you do not specify a pool (i.e. you want only one websocket connection), then a pool of one connection is created. Take a look at SmartWebsocketClient.Pool for details.

Usage

Connecting and sending/receiving messages is very straightforward. Here’s an example:

defmodule MyClient do
  alias SmartWebsocketClient.{Connection, Pool}

  def run do
    connection = %Connection{host: "127.0.0.1", port: 80, path: "/"}
    pool = %Pool{size: 10, overflow: 5}
    SmartWebsocketClient.connect(connection, MyListener, pool)
    SmartWebsocketClient.send("My message")

    # If you don't want to run the client forever, uncomment the line below
    #SmartWebsocketClient.disconnect()
  end
end

defmodule MyListener do
  use SmartWebsocketClient.Listener

  def on_receive(msg) do
    IO.puts "Message received!"
    IO.inspect msg
  end
end

Hopefully the above example gives an idea of the library’s interface. You don’t need to specify a pool if you do not want one. Use connect/2 instead.

Listener

The SmartWebsocketClient.Listener is a behaviour that allows you to act on received messages. It has a very simple interface, as you can see in the example. As a behaviour, you are required to implement the SmartWebsocketClient.Listener.on_receive/1 callback. You can also extend the behaviour to better suit your needs. Take a look at SmartWebsocketClient.Listener for details.

The default Listener behaviour automatically handles ping messages.

Summary

Functions

connect(connection_config, listener, pool_config \\ %{__struct__: SmartWebsocketClient.Pool, name: :websocket_pool, overflow: 0, size: 1, worker: SmartWebsocketClient.Worker})

Connect to the websocket server.

This function allows the user to specify an optional pool. If no pool is specified, only one connection will be created. It still uses the pool transaction mechanism under the hood, since a single connection pool (with no overflow) will is created.

Example

SmartWebsocketClient.connect(connection, listener)
SmartWebsocketClient.connect(connection, listener, pool)
disconnect()

Disconnect from the websocket server.

Calling disconnect/0 will stop all pool workers and kill the supervisor. Currently, it doesn’t disconnect websockets gracefully. That’s TODO.

Example

SmartWebsocketClient.disconnect()
send(msg)

Send a message.

You can send either a string message or a map, which will be encoded to JSON. Throws an ArgumentError if an invalid message is passed as argument.

The client will transparently handle the pool for you. Websocket connections are reserved at a FIFO basis.

Examples

SmartWebsocketClient.send("MyStringMessage")
SmartWebsocketClient.send(%{my: "map"})