To learn more about Mantle and it's internal, see this slide deck.
Add this line to your application's Gemfile:
gem 'mantle'
or install manually by:
$ gem install mantle
Setup a Rails initializer(config/initializers/mantle.rb
):
Mantle.configure do |config|
config.message_bus_redis = Redis.new(host: ENV["MESSAGE_BUS_REDIS_URL"] || 'localhost')
config.message_handlers = {
'account:update' => 'MyMessageHandler',
'order' => ['MyMessageHandler', 'MyOtherMessageHandler']
}
end
The config takes a number of options, many of which have defaults:
Mantle.configure do |config|
config.message_bus_redis = Redis.new(host: 'localhost') # default: localhost
config.logger = Rails.logger # default: Logger.new(STDOUT)
config.redis_namespace = "my-namespace" # default: no namespace
config.message_handlers = {'deal:update' => 'MyHandler'} # default: {}
end
To make the installation of mantle easier, the following command will create these files in a Rails application:
$ rails g mantle:install
If an application only pushes messages on to the queue and doesn't listen, the following configuration is all that's needed:
Mantle.configure do |config|
config.message_bus_redis = Redis.new(host: 'localhost') # default: localhost
config.logger = Rails.logger # default: Logger.new(STDOUT)
end
Publish messages to consumers:
Mantle::Message.new("person:create").publish({ id: message['id'], data: message['data'] })
The first and only argument to Mantle::Message.new
is the channel you want to publish the
message on. The #publish
method takes the message payload (in any format you like)
and pushes the message on to the message bus pub/sub and also adds it to the
catch up queue so offline applications can process the message when they become available.
Define message handler class with .receive
method. For example app/models/my_message_handler.rb
class MyMessageHandler
def self.receive(channel, message)
puts channel # => 'order'
puts message # => { 'id' => 5, 'name' => 'Brandon' }
end
end
To run the listener:
$ bin/mantle
or with configuration:
$ bin/mantle -c ./config/initializers/other_file.rb
To run the processor:
$ bin/sidekiq -q mantle
If the Sidekiq worker should also listen on another queue, add that to the command with:
$ bin/sidekiq -q mantle -q default
It will NOT add the default
queue to processing if there are other queues
enumerated using the -q
option.
Requiring this library causes messages to be appended to an in-memory array.
# test/test_helper.rb
require 'mantle/testing'
class OrderMessage
def perform(message)
Mantle::Message.new("order:create").publish(message)
end
end
class OrderMessageTest < ActiveSupport::TestCase
test "sends a mantle message on created order" do
OrderMessage.new.perform(mantle_message)
assert_equal 1, Mantle.messages.size
msg = Mantle.messages.first
assert_equal "order:create", msg.channel
assert_equal mantle_message, msg.message
end
private
def mantle_message
{ id: 5 }
end
end
Be sure to clear out messages so they don't build up during the test suite:
def teardown
Mantle.clear_all
end
To publish a new version of this gem:
- Branch off of
master
, commit your changes to this branch (incrementing theVERSION
constant) - Merge branch into
master
- Checkout
master
locally and run:
rake build
gem push pkg/mantle-<new version number>.gem
You will be asked for email address and password credentials for rubygems.org
- use the engineering@pipelinedeals.com
credentials
All done! You should see the new version here: https://rubygems.org/gems/mantle
To cut a new github release for this version, click New Release
from this repo's Releases
tab.