Lapin.Connection behaviour (lapin v1.0.3) View Source

RabbitMQ connection handler

This module handles the RabbitMQ connection. It also provides a behaviour for worker module implementation. The worker module should use the Lapin.Connection behaviour and implement the callbacks it needs.

When using the Lapin.Connection behaviour a publish/4 function is injected in the worker module as a shortcut to the Lapin.Connection.publish/5 function which removes the need for passing in the connection and is publicly callable to publish messages on the connection configured for the implementing module.

Link to this section Summary

Types

Connection configuration

Callback result

handle_deliver/2 callback result

Reason for message rejection

t()

Connection

Functions

Closes the connection

Publishes a message to the specified exchange with the given routing_key

Starts a Lapin.Connection with the specified configuration

Callbacks

Called when receiving a basic.cancel from the broker.

Called when receiving a basic.cancel_ok from the broker.

Called when receiving a basic.consume_ok from the broker.

Called when receiving a basic.deliver from the broker.

Called when completing a basic.publish with the broker.

Called when receiving a basic.return from the broker.

Called before handle_deliver/2 to get the payload type.

Link to this section Types

Specs

config() :: [
  consumers: [Lapin.Consumer.config()],
  producers: [Lapin.Producer.config()]
]

Connection configuration

The following keys are supported:

  • module: module using the Lapin.Connection behaviour
  • uri: AMQP URI (String.t | URI.t)
  • host: broker hostname (string | charlist), default: 'localhost'
  • port: broker port (string | integer), default: 5672
  • virtual_host: broker vhost (string), default: "/"
  • username: username (string)
  • password: password (string)
  • auth_mechanisms: broker auth_mechanisms ([:amqplain | :external | :plain]), default: amqp_client default
  • ssl_options: ssl options ([:ssl:ssl_option]), default: none
  • producers: producers to configure ([Producer.config]), default: []
  • consumers: consumers to configure ([Consumer.config]), default: []

Specs

on_callback() :: :ok | {:error, message :: String.t()}

Callback result

Specs

on_deliver() :: :ok | {:reject, reason()} | term()

handle_deliver/2 callback result

Specs

reason() :: term()

Reason for message rejection

Specs

t() :: GenServer.server()

Connection

Link to this section Functions

Specs

close(connection :: t()) :: on_callback()

Closes the connection

Link to this function

publish(connection, exchange, routing_key, payload, options \\ [])

View Source

Specs

publish(
  connection :: t(),
  String.t(),
  String.t(),
  Lapin.Message.Payload.t(),
  options :: Keyword.t()
) :: on_callback()

Publishes a message to the specified exchange with the given routing_key

Link to this function

start_link(configuration, options \\ [])

View Source

Specs

start_link(config(), options :: GenServer.options()) :: GenServer.on_start()

Starts a Lapin.Connection with the specified configuration

Link to this section Callbacks

Specs

handle_cancel(AMQP.Channel.t()) :: on_callback()

Called when receiving a basic.cancel from the broker.

Specs

handle_cancel_ok(AMQP.Channel.t()) :: on_callback()

Called when receiving a basic.cancel_ok from the broker.

Specs

handle_consume_ok(AMQP.Channel.t()) :: on_callback()

Called when receiving a basic.consume_ok from the broker.

This signals successul registration as a consumer.

Specs

handle_deliver(AMQP.Channel.t(), Lapin.Message.t()) :: on_deliver()

Called when receiving a basic.deliver from the broker.

Return values from this callback determine message acknowledgement:

  • :ok: Message was processed by the consumer and should be removed from queue
  • {:reject, reason}: Message was not processed and should be rejected

Any other return value requeues the message to prevent data loss. A crash in the callback code will however reject the message to prevent loops if the message was already delivered before.

The reason term can be used by the application to signal the reason of rejection and is logged in debug.

Specs

handle_publish(AMQP.Channel.t(), Lapin.Message.t()) :: on_callback()

Called when completing a basic.publish with the broker.

Message transmission to the broker is successful when this callback is called.

Specs

handle_return(AMQP.Channel.t(), Lapin.Message.t()) :: on_callback()

Called when receiving a basic.return from the broker.

This signals an undeliverable returned message from the broker.

Specs

Called before handle_deliver/2 to get the payload type.

Should return a data type instance to decode the payload into. A Lapin.Message.Payload implementation must be provided for this type. The default implementation leaves the payload unaltered.