File: README — Documentation for rabbitmq

 ____       _     _     _ _   __  __  ___     ____ _ _            _
|  _ \ __ _| |__ | |__ (_) |_|  \/  |/ _ \   / ___| (_) ___ _ __ | |_
| |_) / _` | '_ \| '_ \| | __| |\/| | | | | | |   | | |/ _ \ '_ \| __|
|  _ < (_| | |_) | |_) | | |_| |  | | |_| | | |___| | |  __/ | | | |_
|_| \_\__,_|_.__/|_.__/|_|\__|_|  |_|\__\_\  \____|_|_|\___|_| |_|\__|

Simplifying RabbitMQ for Ruby apps!

RabbitMQ Client is a ruby client library for applications dealing with RabbitMQ.

It wraps common behaviors needed by publishers and subscribers in an easy and convenient API.
It uses both bunny and connection_pool to manage RabbitMQ communications.
It is extendable using plugins.

Why RabbitMQ Client? Why not bunny and connection_pool directly? Well, gems are just a clients. You still need to write a lot of code to manage proper subscribing and publishing of messages. You need to do error handling, passing request headers to RabbitMQ and maybe logging/instrumenting the message management process. Finally, you also need to consider how to deploy your app and how to start it.

With RabbitMQ Client by your side, all this becomes smooth and easy.

Installation
Usage
1. Configurations
2. Publishing messages to RabbitMQ
Plugins
Development and Testing
Contributing
License

Installation

Add this line to your application's Gemfile:

gem 'rabbitmq_client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rabbitmq_client

Usage

RabbitMQ Client can be used to publsih and subscribe RabbitMQ messages.

Configurations

RabbitMQ Client support the following configurations

Configuration	Description	Default Value
rabbitmq_url	RabbitMQ server URL	amqp://guest:[email protected]:5672
logger_configs.logs_format	RabbitmqClient logs format. values can be either json or plain	plain
logger_configs.logs_level	RabbitmqClient logs level. values can be one of :debug, :info, :error	info
logger_configs.logs_filename	Logs file name, if nil STOUT will be used	nil
logger_configs.logger	Logger object, if nil STOUT logger will created	nil
session_params.heartbeat_publisher	Heartbeat interval for publisher sessions. 0 means no heartbeat	0
session_params.session_pool	Number of sessions with rabbitmq	1
plugins	Array of used plugins	[]
global_store	Global Store used to store tags and headers: RequestHeaderMiddleware RequestStore	nil
whitelist	List of whitelisted headers	['x-request-id'.to_sym]

Full Configuration Example

RabbitmqClient.configure do |config|
  config.rabbitmq_url = "${rabbitmq_url}"
  config.logger_configs = {
    logs_format: 'plain',
    logs_level: :info,
    logs_filename: nil,
    logger: nil
  }
  config.session_params = {
    heartbeat_publisher: 0,
    session_pool: 1
  }
  config.plugins = []
  config.global_store = RequestHeaderMiddleware
  config.whitelist =  ['x-request-id'.to_sym]
end

Append plungins or whitelist items

 RabbitmqClient.plugins << MYRabbitmqClientPlugin
 RabbitmqClient.whitelist << :white_listed_header_key

Publishing messages to RabbitMQ

Publish messages using RabbitmqClient singleton publisher

    # RabbitmqClient.add_exchange(exchange, type, options)
    RabbitmqClient.add_exchange('default.rabbitmq_client', :topic, {})
    # RabbitmqClient.publish(payload, options)
    RabbitmqClient.publish({id: 10, name: 'rabbitmq_client'}, { exchange_name: 'default.rabbitmq_client' })

Create a publisher and use it

    config = {
      rabbitmq_url: val,
      exchange_registry: val,
      session_params: { heartbeat_publisher: val }
    }

   publisher = RabbitmqClient::Publisher.new(config)
   publisher.publish(payload, options)

Plugins

RabbitmqClient plugins are classes that define a callbacks that can be executed before or after events that occuers during RabbitmqClient lifecycle. Current supprted lifecycle events are:

publish: occure when publishing a massage is triggered.

Here is an example where we define a plugin to add some headers to message options before publishing the message.

  class MQTestPlugin < RabbitmqClient::Plugin
    callbacks do |lifecycle|
      lifecycle.before(:publish) do |_message, options|
        options[:headers] = { test_key:  'test'}
      end
    end
  end
  RabbitmqClient.plugins << MQTestPlugin

Development and Testing

After checking out the repo:

run bin/setup to install dependencies
run script/travis.sh to run the tests.

You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wshihadeh/rabbitmq_client.

License

The gem is available as open source under the terms of the MIT License.

Table of Contents