Harmoniser

Harmoniser is a minimalistic approach to interact with the RabbitMQ implementation of AMQP 0-9-1 through Bunny.

Harmoniser provides a long-lived connection to RabbitMQ for efficient publishing and consuming of messages.
Harmoniser issues a thread-safe dedicated channel for each publish/consume use case defined.
Harmoniser offers a concise DSL to differentiate topology definition from other actions such as publishing or consuming.
Harmoniser may run as a dedicated Ruby Process through its CLI as well as a part of other processes like Puma, Unicorn, Sidekiq, or similar.

Getting Started

Add this line to your application's Gemfile:

gem "harmoniser"

Install the gem:

  $ bundle install

Include Harmoniser::Publisher and/or Harmoniser::Subscriber in your classes. For instance, in this scenario, it is assumed that you would like to run publishers and subscribers under the same process.
(Optional) Run Harmoniser CLI in order to process messages from your subscribers:

  $ bundle exec harmoniser --require ./examples/multicast.rb

Inspect the logs to see if everything worked as expected. Look for logs containing harmoniser@.

Concepts

Harmoniser is a library for publishing/consuming messages through RabbitMQ. It enables not only the connection of applications but also the scaling of an application by performing work in the background. This gem is comprised of three parts:

Publisher

The Publisher runs in any Ruby process (puma, unicorn, passenger, sidekiq, etc) and enables you to push messages through a RabbitMQ Exchange. Creating a publisher is as simple as:

require "harmoniser"

class MyPublisher
  include Harmoniser::Publisher
  harmoniser_publisher exchange_name: "my_topic_exchange"
end

MyPublisher.publish({ salute: "Hello World!" }.to_json, routing_key: "my_resource.foo.bar")

The code above assumes that the exchange is already defined. We would like to emphasize that defining RabbitMQ topology (exchanges, queues and bindings) should be performed outside of the class whose role is purely focused on publishing. For more details on how to define the topology, refer to this example.

RabbitMQ

RabbitMQ is the message broker used to publish/consume messages through Harmoniser. It can be configured using Harmoniser.configure as follows:

require "harmoniser"

Harmoniser.configure do |config|
  config.connection_opts = {
    host: "rabbitmq"
  }
end

The options permitted for connection_opts are those accepted by Bunny since Harmoniser is built on top of the widely used Ruby client for RabbitMQ.

Harmoniser Server

Harmoniser server is a process specifically dedicated to running Subscribers that listen to Rabbit Queues. Like any other Ruby process (puma, unicorn, passenger, sidekiq, etc), Harmoniser remains up and running unless OS Signals such as SIGINT or SIGTERM are sent to it. During boot time, the server can register each class from your code that includes Harmoniser::Subscriber module. Creating a subscriber is as simple as:

class MySubscriber
  include Harmoniser::Subscriber
  harmoniser_subscriber queue_name: "my_queue"
end

The code above assumes that the queue and its binding to an exchange are already defined. You can find more details about how this is specified here.

To enable subscribers to receive messages from a queue, you should spin up a dedicated Ruby process as follows:

  $ bundle exec harmoniser --require ./a_path_to_your_ruby_file.rb

For more information about the various options accepted by the Harmoniser process, refer to the Harmoniser CLI documentation.

Contributing

If you are facing issues that you suspect are related to Harmoniser, please consider opening an issue here. Remember to include as much information as possible such as version of Ruby, Rails, Harmoniser, OS, etc.

If you believe you have encountered a potential bug, providing detailed information about how to reproduce it can greatly expedite the fix.

Code

To contribute to this codebase, you will need to setup your local development using the following steps:

# Prepare the environment for working locally.
  $ make build
# Perform the desired changes into your local copy
  $ make test

You can also access the running container by executing $ make shell and then execute any commands related to Harmoniser within its isolated environment.

License

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

Author

Jose Lloret, jollopre@gmail.com

jollopre/harmoniser