hare v0.2.2 Hare.Publisher behaviour

A behaviour module for implementing AMQP publisher processes.

The Hare.Publisher module provides a way to create processes that hold, monitor, and restart a channel in case of failure, exports a function to publish messages to an exchange, and some callbacks to hook into the process lifecycle.

An example Hare.Publisher process that only sends every other message:

defmodule MyPublisher do
  use Hare.Publisher

  def start_link(conn, config, opts \ []) do
    Hare.Publisher.start_link(__MODULE__, conn, config, :ok, opts)
  end

  def publish(publisher, payload, routing_key) do
    Hare.Publisher.publish(publisher, payload, routing_key)
  end

  def init(:ok) do
    {:ok, %{last_ignored: false}}
  end

  def before_publication(_payload, _routing_key, _opts, %{last_ignored: false}) do
    {:ignore, %{last_ignored: true}}
  end
  def before_publication(_payload, _routing_key, _opts, %{last_ignored: true}) do
    {:ok, %{last_ignored: false}}
  end
end

Channel handling

When the Hare.Publisher starts with start_link/5 it runs the init/1 callback and responds with {:ok, pid} on success, like a GenServer.

After starting the process it attempts to open a channel on the given connection. It monitors the channel, and in case of failure it tries to reopen again and again on the same connection.

Context setup

The context setup process for a publisher is to declare its exchange.

Every time a channel is open the context is set up, meaning that the exchange is declared through the new channel based on the given configuration.

The configuration must be a Keyword.t that may contain a single key: :exchange whose value is the configuration for the Hare.Context.Action.DeclareExchange. Check it for more detailed information. If the :exchange key is omited, the default exchange will be used.

Summary

Functions

See Hare.Actor.call/2

See Hare.Actor.call/3

See Hare.Actor.cast/2

Publishes a message to an exchange through the Hare.Publisher process

See Hare.Actor.reply/2

Starts a Hare.Publisher process linked to the current process

Callbacks

Called after a message has been published to the exchange

Called before a message will be published 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 publisher process has successfully opened AMQP channel

Called when the AMQP publisher has been disconnected from the AMQP broker

Called when the process receives a message

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

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

Types

config()
config() :: [config_option]
config_option()
config_option() :: {:exchange, Hare.Context.Action.DeclareExchange.config}
message()
message() :: term
meta()
meta() :: map
opts()
opts() :: Hare.Adapter.opts
payload()
payload() :: Hare.Adapter.payload
routing_key()
routing_key() :: Hare.Adapter.routing_key
state()
state() :: term

Functions

call(server, message)

See Hare.Actor.call/2.

call(server, message, timeout)

See Hare.Actor.call/3.

cast(server, message)

See Hare.Actor.cast/2.

publish(client, payload, routing_key \\ "", opts \\ [])
publish(GenServer.server, payload :: term, routing_key, opts) :: :ok

Publishes a message to an exchange through the Hare.Publisher process.

reply(from, message)

See Hare.Actor.reply/2.

start_link(mod, conn, config, initial, opts \\ [])
start_link(module, GenServer.server, config, initial :: term, GenServer.options) :: GenServer.on_start

Starts a Hare.Publisher process linked to the current process.

This function is used to start a Hare.Publisher 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 publisher (describing the exchange to declare)
  • initial - the value that will be given to init/1
  • opts - the GenServer options

Callbacks

after_publication(payload, routing_key, opts, state)
after_publication(payload, routing_key, opts :: term, state) ::
  {:ok, state} |
  {:stop, reason :: term, state}

Called after a message has been published 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 enter the main loop with the given state.

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

before_publication(message, routing_key, opts, state)
before_publication(message, routing_key, opts :: term, state) ::
  {:ok, state} |
  {:ok, payload, routing_key, opts :: term, state} |
  {:ignore, state} |
  {:stop, reason :: term, state}

Called before a message will be published 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 message to be sent with no modification, and enter the main loop with the given state.

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

Returning {:ignore, state} will ignore that message and enter the main loop again 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.

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.

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.

handle_connected(state)
handle_connected(state) ::
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when the publisher process has successfully opened AMQP channel.

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

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

handle_disconnected(reason, state)
handle_disconnected(reason :: term, state) ::
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when the AMQP publisher has been disconnected from the AMQP broker.

Returning {:noreply, state} causes the process to enter the main loop with the given state. The publisher will not be able to send any new messages until connection to AMQP broker is established again.

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

handle_info(message, state)
handle_info(message, state) ::
  {:noreply, state} |
  {:stop, reason :: term, state}

Called when the process receives a message.

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.

init(initial)
init(initial :: term) ::
  {:ok, state} |
  :ignore |
  {:stop, reason :: term}

Called when the publisher 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 and declare the exchange. 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.

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.