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/orHarmoniser::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