StompJob

StompJob gives a Resque-like interface for message brokers using the STOMP protocol. It uses https://github.com/stompgem/stomp under the hood.

Installation

Add this line to your application's Gemfile:

gem 'stomp_job'

And then execute:

$ bundle

Or install it yourself as:

$ gem install stomp_job

Usage

To create a worker class, simply add include StompJob::Worker to your class, configure it with the stomp_options class method, and define a perform method.

To enqueue a message, call YourWorker.enqueue(*args), where YourWorker is your worker class, and *args has the same arity as your perform method.

To run your workers, run ./bin/stomper. Make sure that stomper has your workers loaded by passing --require flags. e.g.

./bin/stomper --require=./examples/scream_worker

See the examples/ directory for example usage.

Rails

If you're working with rails, start the workers by running ./bin/stomper --rails instead.

Additionally, there is an ActiveJob adapter included with this gem. To use it, simply add

require 'stomp_job/extensions/active_job_adapter'
config.active_job.queue_adapter = :stomp_job

to your config/application.rb file.

STOMP Broker Connection

You can configure the connection to your STOMP broker as follows:

StompJob::Configuration.setup do |config|
  config[:hosts] = [
    {login: "your_username", passcode: "your_password", host: "example.com", port: 61613}
  ]
  config[:reliable] = true
  config[:initial_reconnect_delay] = 0.01
  # config[:some_option] = some_value
end

Alternatively you can call

StompJob::Configuration.load_config!(file="config/stomp_job.yml")

to load connection information out of a config file. This is the recommended method for loading config from a rails app.

Testing

Any contributions should include tests. There is a dockerized ArtemisMQ instance in spec/activemq-artemis/ that you can test against. Credit for the Docker stuff goes to https://github.com/vromero/activemq-artemis-docker.

Testing running the ArtemisMQ instance are NOT run by default, and can be run with

rspec --tag integration

Make sure you have the ArtemisMQ docker instance running locally when you run this or else tests will hang. Assuming a sane docker setup, the docker instance can be launched with

docker run -d --name artemis -p 61613:61613 vromero/activemq-artemis

TODO

The below are some current issues/features that could still be implemented for this gem:

• Set up some form of logging. Logging should be configurable, e.g. in rails, you should be able to say something like StompJob.logger = Rails.logger
• Write an enqueue_at method for ActiveJob::QueueAdapters::StompJobAdapter.
• Exceptions die too quietly. Can they raise an exception in the main thread? Can we implement some sort of retry functionality?
• Implement a more graceful shutdown. We could at least unsubscribe the STOMP connections when shutting down.
• Clean up ArtemisMQ spec? Can we reasonably (read: without hacks) make that a part of the rspec suite proper?

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mGageTechOps/stomp_job. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

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