Create an Erps client GenServer.

The best way to think of an Erps client is that it is a GenServer that forwards its call/2 and cast/2 callbacks to a remote GenServer over a LAN or WAN. This callbacks would normally be provided by standard GenServer.call/2 and GenServer.cast/2 semantics over erlang distribution but sometimes you just don't want that (see Erps).

Basic operation

Presuming you have set up an Erps server GenServer on some host at @hostname, you can connect the client and the server simply by instantiating the server module.

Example

defmodule ErpsClient do
  use Erps.Client

  @hostname <...>
  @port <...>

  def start_link, do: Erps.Client.start_link(__MODULE__, :ok,
    server: @hostname, port: @port, tls_opts: [...])

  def init(init_state), do: {:ok, init_state}
end

{:ok, client} = ErpsClient.start_link
GenServer.call(client, :some_remote_call)
# => :some_remote_response

Module options

• :version the version of your Erps API messages. Should be a SemVer string. see Version for more information.
• :identifier (optional) a binary identifier for your Erps API endpoint. Maximum 36 bytes, suggested to be human-readable. This must match the identifier on the server in order for there to be a successful connection.
• :safe (see :erlang.binary_to_term/2), for decoding terms. If set to false, then allows undefined atoms and lambdas to be passed via the protocol. This should be used with extreme caution, as disabling safe mode can be an attack vector. (defaults to true)

Example

defmodule MyClient do
  use Erps.Client, version: "0.2.4",
                   identifier: "my_api",
                   safe: false

  def start_link(iv) do
    Erps.Client.start_link(__MODULE__, init,
      server: "my_api-server.example.com",
      port: 4747,
      transport: Transport.Tls,
      tls_opts: [...])
  end

  def init(iv), do: {:ok, iv}
end

Important Notes

• Calls are non-blocking for the Erps clients (and can be for the servers, if you so implement them). You may issue multiple, asynchronous calls across the network from different processes and they will be routed correctly and will only interfere with each other in terms of the connection arbitration overhead.
• Calls reply immediately with the atom :disconnected if the erps client is not currently connected to its server.
• handle_continue/2 is currently not supported. This is a limitation in the Connection library.