ExRabbitMQ v2.10.0 ExRabbitMQ.Consumer behaviour View Source

A behaviour module that abstracts away the handling of RabbitMQ connections and channels.

It abstracts the handling of message delivery and acknowlegement.

It also provides hooks to allow the programmer to wrap the consumption of a message without having to directly access the AMPQ interfaces.

For a connection configuration example see ExRabbitMQ.ConnectionConfig.

For a queue configuration example see ExRabbitMQ.Consumer.QueueConfig.

Example usage for a consumer implementing a GenServer

defmodule MyExRabbitMQConsumer do
  @module __MODULE__

  use GenServer
  use ExRabbitMQ.Consumer, GenServer

  def start_link() do
    GenServer.start_link(@module, :ok)
  end

  def init(state) do
    new_state =
      xrmq_init(:my_connection_config, :my_queue_config, state)
      |> xrmq_extract_state()

    {:ok, new_state}
  end

  # required override
  def xrmq_basic_deliver(payload, meta, state) do
    # your message delivery logic goes here...

    {:noreply, state}
  end

  # optional override when there is a need to do setup the channel right after the connection has been established.
  def xrmq_channel_setup(channel, state) do
    # any channel setup goes here...

    {:ok, state}
  end

  # optional override when there is a need to setup the queue and/or exchange just before the consume.
  def xrmq_queue_setup(channel, queue, state) do
    # The default queue setup uses the exchange, exchange_opts, bind_opts and qos_opts from
    # the queue's configuration to setup the QoS, declare the exchange and bind it with the queue.
    # Your can override this function, but you can also keep this functionality of the automatic queue setup by
    # calling super, eg:
    {:ok, state} = super(channel, queue, state)

    # any other queue setup goes here...
  end
end

Link to this section Summary

Callbacks

This overridable function can be called whenever no_ack is set to false and the user wants to ack a message

This overridable hook is called as a response to a :basic_cancel message

This callback is the only required callback (i.e., without any default implementation) and is called as a response to a :basic_consume message

This overridable function publishes the payload to the exchange using the provided routing_key

This overridable function can be called whenever no_ack is set to false and the user wants to reject a message

This overridable function can be called whenever no_ack is set to false and the user wants to reject a message

This hook is called when a connection has been established and a new channel has been opened

This hook is called automatically, if start_consuming was true when xrmq_init/4

Helper function that extracts the state argument from the passed in tuple

Returns the connection configuration as it was passed to xrmq_init/4

Returns a part of the :exrabbitmq configuration section, specified with the key argument

Returns the queue configuration as it was passed to xrmq_init/4

Initiates a connection or reuses an existing one

This hook is called automatically as part of the flow in xrmq_consume/1

Link to this section Callbacks

Link to this callback xrmq_basic_ack(delivery_tag, state) View Source
xrmq_basic_ack(delivery_tag :: String.t, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

This overridable function can be called whenever no_ack is set to false and the user wants to ack a message.

It is passed the delivery_tag of the request and by default it simply acks the message as per the RabbitMQ API.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_basic_cancel(cancellation_info, state) View Source
xrmq_basic_cancel(cancellation_info :: any, state :: any) ::
  {:noreply, new_state :: term} |
  {:noreply, new_state :: term, timeout | :hibernate} |
  {:noreply, [event :: term], new_state :: term} |
  {:noreply, [event :: term], new_state :: term, :hibernate} |
  {:stop, reason :: term, new_state :: term}

This overridable hook is called as a response to a :basic_cancel message.

It is passed the cancellation_info of the request and by default it logs an error and returns {:stop, :basic_cancel, state}.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_basic_deliver(payload, meta, state) View Source
xrmq_basic_deliver(payload :: term, meta :: term, state :: term) ::
  {:noreply, new_state :: term} |
  {:noreply, new_state :: term, timeout | :hibernate} |
  {:noreply, [event :: term], new_state :: term} |
  {:noreply, [event :: term], new_state :: term, :hibernate} |
  {:stop, reason :: term, new_state :: term}

This callback is the only required callback (i.e., without any default implementation) and is called as a response to a :basic_consume message.

It is passed the payload of the request as well as the meta object or the message.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_basic_publish(payload, exchange, routing_key, opts) View Source
xrmq_basic_publish(payload :: term, exchange :: String.t, routing_key :: String.t, opts :: [term]) ::
  :ok |
  {:error, reason :: :blocked | :closing | :no_channel}

This overridable function publishes the payload to the exchange using the provided routing_key.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_basic_reject(delivery_tag, state) View Source
xrmq_basic_reject(delivery_tag :: String.t, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

This overridable function can be called whenever no_ack is set to false and the user wants to reject a message.

It is passed the delivery_tag of the request and by default it simply rejects the message as per the RabbitMQ API.

This function simply calls xrmq_basic_reject/3 with opts set to [].

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_basic_reject(delivery_tag, opts, state) View Source
xrmq_basic_reject(delivery_tag :: String.t, opts :: term, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

This overridable function can be called whenever no_ack is set to false and the user wants to reject a message.

It is passed the delivery_tag of the request and by default it simply rejects the message as per the RabbitMQ API.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_channel_setup(channel, state) View Source
xrmq_channel_setup(channel :: term, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

This hook is called when a connection has been established and a new channel has been opened.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_consume(state) View Source
xrmq_consume(state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

This hook is called automatically, if start_consuming was true when xrmq_init/4.

If not, then the user has to call it to start consuming.

It is invoked when a connection has been established and a new channel has been opened.

Its flow is to:

  1. Declare the queue
  2. Run xrmq_queue_setup/3
  3. Start consuming from the queue

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

Link to this callback xrmq_extract_state(arg0) View Source
xrmq_extract_state({:ok, state :: term} | {:error, reason :: term, state :: term}) :: state :: term

Helper function that extracts the state argument from the passed in tuple.

Link to this callback xrmq_get_connection_config() View Source
xrmq_get_connection_config() :: term

Returns the connection configuration as it was passed to xrmq_init/4.

This configuration is set in the wrapper process’s dictionary.

For the configuration format see the top section of ExRabbitMQ.Consumer.

Link to this callback xrmq_get_env_config(key) View Source
xrmq_get_env_config(key :: atom) :: keyword

Returns a part of the :exrabbitmq configuration section, specified with the key argument.

For the configuration format see the top section of ExRabbitMQ.Consumer.

Link to this callback xrmq_get_queue_config() View Source
xrmq_get_queue_config() :: term

Returns the queue configuration as it was passed to xrmq_init/4.

This configuration is set in the wrapper process’s dictionary.

For the configuration format see the top section of ExRabbitMQ.Consumer.

Link to this callback xrmq_init(connection_config, queue_config, start_consuming, state) View Source
xrmq_init(connection_config :: struct, queue_config :: struct, start_consuming :: boolean, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}
xrmq_init(connection_config :: struct, queue_key :: atom, start_consuming :: boolean, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}
xrmq_init(connection_key :: atom, queue_config :: struct, start_consuming :: boolean, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}
xrmq_init(connection_key :: atom, queue_key :: atom, start_consuming :: boolean, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

Initiates a connection or reuses an existing one.

When a connection is established then a new channel is opened.

Next, xrmq_channel_setup/2 is called to do any extra work on the opened channel.

If start_consuming is true then xrmq_consume/1 is called automatically.

This variant accepts a ExRabbitMQ.Connection and a ExRabbitMQ.Consumer.QueueConfig structs as the arguments for the connection_config and queue_config parameters.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.

For the configuration format see the top section of ExRabbitMQ.Consumer.

Link to this callback xrmq_queue_setup(channel, queue, state) View Source
xrmq_queue_setup(channel :: term, queue :: String.t, state :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term, new_state :: term}

This hook is called automatically as part of the flow in xrmq_consume/1.

It allows the user to run extra queue setup steps when the queue has been declared. The default queue setup uses the exchange, exchange_opts, bind_opts and qos_opts from the queue’s configuration to setup the QoS, declare the exchange and bind it with the queue.

The wrapper process’s state is passed in to allow the callback to mutate it if overriden.