Messaging adapter gem for Ruby, useful for using message brokers (RabbitMQ, Kafka,...) in Ruby applications
MIT License
Messaging adapter gem for Ruby, useful for using message brokers (RabbitMQ, Kafka,...) in any Ruby application (including Rails applications).
To use this gem and apply the instructions in the example below you must have the following things done:
Install Ruby (version 2.4.2 or higher)
Install RabbitMQ by following the instructions in the official site or if you know how to use Docker you can make and run your own RabbitMQ container from this docker image.
Browse to the administartion portal of RabbitMQ which will be by default on http://localhost:15672/
.
Create a new exchange
to be your message router and name it test
then create a new queue test_queue
to be consumed then go to the exchange and bind it to the new queue so when someone publish a message to the exchange it will be directly routed to the binded queue(s) as one-to-many topology.
If you are confused a little bit then you should read about message brokers
and especially RabbitMQ
which is used in the below example.
Please note that points #3 and #4 are optional and written just to make the example mentioned below work.
In your Ruby application install the gem from the .gem
file using the terminal.
$ gem install messaging-adapter-x.y.z.gem
$ gem install messaging-adapter
In the application entrypoint create the broker instance with your desired adapter.
broker = broker = MessagingAdapter::MessageBroker.new(:RabbitMQ)
Use that instance in your application to publish a message Hey there!!
to the exchange test
.
broker.publish('test', 'Hey there!!')
Use that instance in your application to subscribe to a topic/queue test_queue
.
broker.subscribe('test_queue') do |payload|
puts "[x] Received message: #{payload}"
end
For more details please check the test.rb
in the root of this repository.
Add the gem to the Gemfile
like this:
gem 'messaging-adapter'
Run bundle install
command in the terminal.
Go to the config/application.rb
file in your application.
Add the following line before the Bundler.require
call:
require "messaging_adapter"
Add the following code in the last of the Application
class:
class << self
attr_reader :msg_broker
end
config.after_initialize do
@msg_broker = MessagingAdapter::MessageBroker.new(:RabbitMQ)
end
Here we declared a class variable msg_broker
with reader accessor to be our single instance of the MessageBroker
in the application, this will insure that the connection with the message broker (RabbitMQ for example) will be managed correctly.
In your controller for example if you want to publish a message you can do it by writing in your action:
RailsApp01::Application.msg_broker.publish('test', 'Hey there!!')
Our example application named rails-app01
so we accessed the msg_broker
on the Application
class in the application module RailsApp01
.
There are some options can be passed as a hash when using publish
and subscribe
methods:
publish
options:
direct_to_q
: boolean value (for RabbitMQ adapter), false
by default, if true
then the message will be published to the queue directly, not to an exchange;
b.publish('registration', 'my message')
: this will publish a message to an exchange (router) named registration
.
b.publish('registration', 'my message', direct_to_q: true)
: this will publish a message directlyto a queue named registration
.
subscribe
options:
block
: boolean value (for RabbitMQ adapter), true
by default, if true
the subscriber will block the caller thread while working, otherwise no thread blocking.The follwoing are the environment variables which can be used in .env
files to connect to the message broker (RabbitMQ or Kafka) with their default values if not provided:
Please check the .env.example
file for more details.