freddy v0.9.1 Freddy.RPC.Client behaviour

This module allows to build RPC client for any Freddy-compliant microservice.

Example:

defmodule PaymentsService do
  use Freddy.RPC.Client

  @config [routing_key: "Payments", timeout: 3500]

  def start_link(conn, initial, opts \\ []) do
    Freddy.RPC.Client.start_link(__MODULE__, conn, @config, initial, opts)
  end
end

{:ok, client} = PaymentsService.start_link()
PaymentsService.request(client, %{type: "get_history", site_id: "xxx"})

Link to this section Summary

Callbacks

Called before a request will be performed to the exchange

Called when the process receives a call message sent by call/3. This callback has the same arguments as the GenServer equivalent and the :reply, :noreply and :stop return tuples behave the same

Called when the process receives a cast message sent by cast/3. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same

Called when the process receives a message. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same

Called when the AMQP server has registered the process as a consumer of the server-named queue and it will start to receive messages

Called when the RPC client process is first started. start_link/5 will block until it returns

Called when a response has been received, before it is delivered to the caller

Called when a request has timed out

This callback is the same as the GenServer equivalent and is called when the process terminates. The first argument is the reason the process is about to exit with

Link to this section Types

Link to this type config()
config() :: [timeout: timeout, exchange: Hare.Context.Action.DeclareExchange.config, routing_key: routing_key]
Link to this type meta()
meta() :: map
Link to this type payload()
payload() :: term
Link to this type response()
response() :: term
Link to this type routing_key()
routing_key() :: Hare.Adapter.routing_key
Link to this type state()
state() :: term

Link to this section Functions

Link to this function call(client, message, timeout)

See Hare.RPC.Client.call/3.

Link to this function request(client, payload, opts \\ [])
request(GenServer.server, payload, GenServer.options) ::
  {:ok, response} |
  {:error, reason :: term} |
  {:error, reason :: term, hint :: term}

Performs a RPC request and blocks until the response arrives.

Link to this function start_link(mod, conn, config, initial, opts \\ [])
start_link(module, GenServer.server, config, initial :: term, GenServer.options) ::
  GenServer.on_start |
  no_return

Starts a Freddy.RPC.Client process linked to the current process.

This function is used to start a Freddy.RPC.Client process in a supervision tree. The process will be started by calling init with the given initial value.

Arguments:

  • mod - the module that defines the server callbacks (like GenServer)
  • conn - the pid of a Hare.Core.Conn process
  • config - the configuration of the RPC Client (describing the exchange, routing_key and timeout value)
  • initial - the value that will be given to init/1
  • opts - the GenServer options
Link to this function stop(client, reason)

See GenServer.stop/2.

Link to this section Callbacks

Link to this callback before_request(payload, opts, state)
before_request(payload, opts :: term, state) ::
  {:ok, state} |
  {:ok, meta, state} |
  {:ok, payload, opts :: term, state} |
  {:ok, payload, opts :: term, meta, state} |
  {:reply, response, state} |
  {:stop, reason :: term, response, state} |
  {:stop, reason :: term, state}

Called before a request will be performed to the exchange.

It receives as argument the message payload, the routing key, the options for that publication and the internal state.

Returning {:ok, state} will cause the request to be performed with no modification, block the client until the response is received, and enter the main loop with the given state.

Returnung {:ok, meta, state} will do the same as {:ok, state}, but returned meta will be given as a 2nd argument in on_response/3 and as a 1st argument in on_timeout/3 callback.

Returning {:ok, payload, opts, state} will cause the given payload, routing key and options to be used instead of the original ones, block the client until the response is received, and enter the main loop with the given state.

Returning {:ok, payload, opts, meta, state will do the same as {:ok, payload, opts, state}, but returned meta will be given as a 2nd argument in on_response/3 and as a 1st argument in on_timeout/3 callback.

Returning {:reply, response, state} will respond the client inmediately without performing the request with the given response, and enter the main loop again with the given state.

Returning {:stop, reason, response, state} will not send the message, respond to the caller with response, and terminate the main loop and call terminate(reason, state) before the process exits with reason reason.

Returning {:stop, reason, state} will not send the message, terminate the main loop and call terminate(reason, state) before the process exits with reason reason.

Link to this callback handle_call(request, arg1, state)
handle_call(request :: term, GenServer.from, state) ::
  {:reply, reply :: term, state} |
  {:reply, reply :: term, state, timeout | :hibernate} |
  {:noreply, state} |
  {:noreply, state, timeout | :hibernate} |
  {:stop, reason :: term, state} |
  {:stop, reason :: term, reply :: term, state}

Called when the process receives a call message sent by call/3. This callback has the same arguments as the GenServer equivalent and the :reply, :noreply and :stop return tuples behave the same.

Link to this callback handle_cast(request, state)
handle_cast(request :: term, state) ::
  {:noreply, state} |
  {:noreply, state, timeout | :hibernate} |
  {:stop, reason :: term, state}

Called when the process receives a cast message sent by cast/3. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same.

Link to this callback handle_info(message, state)
handle_info(message :: term, state) ::
  {:noreply, state} |
  {:noreply, state, timeout | :hibernate} |
  {:stop, reason :: term, state}

Called when the process receives a message. This callback has the same arguments as the GenServer equivalent and the :noreply and :stop return tuples behave the same.

Link to this callback handle_ready(meta, state)
handle_ready(meta, state) ::
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when the AMQP server has registered the process as a consumer of the server-named queue and it will start to receive messages.

Returning {:noreply, state} will causes the process to enter the main loop with the given state.

Returning {:stop, reason, state} will not send the message, terminate the main loop and call terminate(reason, state) before the process exits with reason reason.

Link to this callback init(initial)
init(initial :: term) ::
  {:ok, state} |
  :ignore |
  {:stop, reason :: term}

Called when the RPC client process is first started. start_link/5 will block until it returns.

It receives as argument the fourth argument given to start_link/5.

Returning {:ok, state} will cause start_link/5 to return {:ok, pid} and attempt to open a channel on the given connection, declare the exchange, declare a server-named queue, and consume it. After that it will enter the main loop with state as its internal state.

Returning :ignore will cause start_link/5 to return :ignore and the process will exit normally without entering the loop, opening a channel or calling terminate/2.

Returning {:stop, reason} will cause start_link/5 to return {:error, reason} and the process will exit with reason reason without entering the loop, opening a channel, or calling terminate/2.

Link to this callback on_response(response, meta, state)
on_response(response, meta, state) ::
  {:reply, response, state} |
  {:noreply, state} |
  {:stop, reason :: term, response, state} |
  {:stop, reason :: term, state}

Called when a response has been received, before it is delivered to the caller.

It receives as argument the message payload, the routing key, the options for that publication, the response, and the internal state.

Returning {:reply, reply, state} will cause the given reply to be delivered to the caller instead of the original response, and enter the main loop with the given state.

Returning {:noreply, state} will enter the main loop with the given state without responding to the caller (that will eventually timeout or keep blocked forever if the timeout was set to :infinity).

Returning {:stop, reason, reply, state} will deliver the given reply to the caller instead of the original response and call terminate(reason, state) before the process exits with reason reason.

Returning {:stop, reason, state} not reply to the caller and call terminate(reason, state) before the process exits with reason reason.

Link to this callback on_timeout(meta, state)
on_timeout(meta :: term, state) ::
  {:reply, response, state} |
  {:noreply, state} |
  {:stop, reason :: term, response, state} |
  {:stop, reason :: term, state}

Called when a request has timed out.

Returning {:reply, reply, state} will cause the given reply to be delivered to the caller, and enter the main loop with the given state.

Returning {:noreply, state} will enter the main loop with the given state without responding to the caller (that will eventually timeout or keep blocked forever if the timeout was set to :infinity).

Returning {:stop, reason, reply, state} will deliver the given reply to the caller, and call terminate(reason, state) before the process exits with reason reason.

Returning {:stop, reason, state} will not reply to the caller and call terminate(reason, state) before the process exits with reason reason.

Link to this callback terminate(reason, state)
terminate(reason :: term, state) :: any

This callback is the same as the GenServer equivalent and is called when the process terminates. The first argument is the reason the process is about to exit with.