ruote-resque 0.1.0

data/lib/ruote/resque/participant_registrar.rb

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+
+module Ruote
+module Resque
+
+# An object to easy Participant registration
+# @example Register a participant
+#     # Will register a participant be_awesome
+#     # that enqueues the Job MyAwesomeJob to my_queue
+#     Ruote::Resque.register(dashboard) do
+#       be_awesome 'MyAwesomeJob', :my_queue
+#       # or via the participant method
+#       participant 'be_awesome', 'MyAwesomeJob', :my_queue
+#     end
+class ParticipantRegistrar
+
+  # @param [Ruote::Dashboard] dashboard
+  # @return [Ruote::Resque::ParticipantRegistrar]
+  def initialize(dashboard)
+    @dashboard = dashboard
+  end
+
+  # Implements the dsl to register participants
+  # @see Ruote::Resque::ParticipantRegistrar
+  def method_missing(method_name, *args, &block)
+    participant(method_name.to_s, *args, &block)
+  end
+
+  # Call this method to register a participant (or use method_missing)
+  # @param [#to_s] name the name of the participant
+  # @param [#to_s] klass the class of the Resque job
+  # @param [#to_s] queue the queue of the job
+  # @param [Hash] options options to be passed on to +Ruote::Resque::Participant+
+  # @return [void]
+  def participant(name, klass, queue, options = {})
+    options.merge!({ :class => klass, :queue => queue })
+    @dashboard.register_participant(name, Ruote::Resque::Participant, options)
+  end
+
+end
+end
+end

data/lib/ruote/resque/receiver.rb

@@ -0,0 +1,140 @@
+# encoding: UTF-8
+
+module Ruote
+module Resque
+
+  # Raised when a job different from `Ruote::Resque::ReplyJob
+  # is found on the reply_queue.
+  class InvalidJob < RuntimeError
+  end
+
+  # Raised when a reply job has an invalid workitem.
+  class InvalidWorkitem < RuntimeError
+  end
+
+  # The receiver will poll the reply_queue in Resque, waiting for reply jobs.
+  # It does so in a new thread.
+  #
+  # By default it polls the reply_queue every 5 seconds, but this is configurable via
+  # the `interval` configuration option. See {Ruote::Resque}.
+  #
+  # You should launch the Receiver as soon as your engine is set up.
+  #
+  # @example Running a ruote-resque Receiver
+  #     Ruote::Resque::Receiver.new(dashboard)
+  #
+  # @example Overriding the handle_error method for custom exception handling
+  #     class Ruote::Resque::Receiver
+  #       def handle_error(e)
+  #         MyErrorHandler.handle(e)
+  #       end
+  #     end
+  #
+  #     Ruote::Resque::Receiver.new(dashboard)
+  #
+  class Receiver < ::Ruote::Receiver
+
+    # Retunrs a new Receiver instance and spawns a worker thread.
+    # @param [Ruote::Dashboard] cwes Accepts context, worker, engine or storage
+    # @param [Hash] options Passed on to Ruote, currently unused.
+    # @return [Receiver]
+    def initialize(cwes, options = {})
+      super
+      @listener = listen
+    end
+
+    # Stops the worker thread.
+    # @return [void]
+    def shutdown
+      @listener.kill
+    end
+
+    # Called when an error is raised during the poll/reserve/process flow of the Receiver.
+    # You should override this method for custom error handling.
+    # By default it just logs the exception.
+    # @param [Exception] e
+    # @return [void]
+    def handle_error(e)
+      Ruote::Resque.logger.error(e)
+    end
+
+    private
+
+    def listen
+
+      Thread.new do
+        loop do
+          work
+        end
+      end
+
+    end
+
+    def work
+
+      reserve
+
+    # handle_error may raise an exception itself
+    # in this case protect the thread
+    rescue => e
+      Ruote::Resque.logger.error('*** UNCAUGHT EXCEPTION IN RUOTE::RESQUE::RECEIVER ***')
+      Ruote::Resque.logger.error(e)
+    end
+
+    def reserve
+
+      if job = ::Resque.reserve(Ruote::Resque.configuration.reply_queue)
+        validate_job(job)
+        process(job)
+      else
+        sleep Ruote::Resque.configuration.interval
+      end
+
+    rescue => e
+      handle_error(e)
+    end
+
+    def process(job)
+
+      job_arguments = job.args
+      item = job_arguments.pop
+
+      if job_arguments.any?
+        flunk(item, *job_arguments)
+      else
+        receive(item)
+      end
+
+    rescue => e
+      # Fail the job on Resque, then raise to let handle_error do it's work
+      job.fail(e)
+      raise
+    end
+
+    def validate_job(job)
+
+      job_class = job.payload_class.to_s
+      unless job_class == 'Ruote::Resque::ReplyJob'
+        raise InvalidJob.new(job_class)
+      end
+
+      item = job.args.last
+      unless item.is_a?(Hash) && item['fields'] && item['fei']
+        raise InvalidWorkitem.new(item.inspect)
+      end
+
+    end
+
+    def flunk(workitem, class_name, message, backtrace)
+
+      error = Ruote::ReceivedError.new(class_name, message, backtrace)
+      args = [error, message, backtrace]
+
+      super(workitem, *args)
+
+    end
+
+  end
+
+end
+end

data/lib/ruote/resque/reply_job.rb

@@ -0,0 +1,23 @@
+# encoding: UTF-8
+
+module Ruote
+module Resque
+
+  # An empty job used for message passing between job instances and ruote-resque.
+  module ReplyJob
+
+    # @return [#to_s] The configured queue for message passing.
+    def self.queue
+      Ruote::Resque.configuration.reply_queue
+    end
+
+    # This is a no-op.
+    # @return [void]
+    def self.perform(*args)
+      # noop
+    end
+
+  end
+
+end
+end

data/lib/ruote/resque/version.rb

@@ -0,0 +1,7 @@
+# encoding: UTF-8
+
+module Ruote
+  module Resque
+    VERSION = '0.1.0'
+  end
+end

data/ruote-resque.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ruote/resque/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ruote-resque"
+  spec.version       = Ruote::Resque::VERSION
+  spec.authors       = ["Adrien Kohlbecker"]
+  spec.email         = ["adrien.kohlbecker@gmail.com"]
+  spec.description   = %q{Resque participant/receiver pair for Ruote}
+  spec.summary       = %q{Resque participant/receiver pair for Ruote}
+  spec.homepage      = "https://github.com/adrienkohlbecker/ruote-resque"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'resque'
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency 'mutant'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'redcarpet'
+end

data/spec/lib/ruote/resque/job_spec.rb

@@ -0,0 +1,129 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+describe Ruote::Resque::Job do
+
+  context '::after_perform_reply_to_ruote' do
+
+    class Job
+      @queue = :rspec
+      extend Ruote::Resque::Job
+      def self.perform(workitem)
+        workitem['is_resque_awesome'] = true
+      end
+    end
+
+    let(:workitem) { { 'is_rspec_awesome' => true } }
+    let(:enqued_job) { ::Resque.reserve(Ruote::Resque.configuration.reply_queue) }
+
+    context 'enqueues a job' do
+
+      before :each do
+        Job.after_perform_reply_to_ruote(workitem)
+      end
+
+      it 'to resque' do
+        expect(enqued_job.class).to eq ::Resque::Job
+      end
+
+      it 'to the configured reply_queue' do
+        expect(enqued_job.queue).to eq Ruote::Resque.configuration.reply_queue
+      end
+
+      it 'with the workitem as arguments' do
+        expect(enqued_job.args).to eq [workitem]
+      end
+
+    end
+
+    context 'replies with the mutated workitem' do
+
+      let(:mutated_workitem) { { 'is_rspec_awesome' => true, 'is_resque_awesome' => true } }
+
+      before :each do
+        Resque.inline = true
+      end
+
+      after :each do
+        Resque.inline = false
+      end
+
+      it 'allows the workitem to be mutated' do
+
+        Ruote::Resque::ReplyJob.should_receive(:perform).with(mutated_workitem)
+        Resque.enqueue(Job, workitem)
+
+      end
+
+    end
+
+  end
+
+  context '::on_failure_reply_to_ruote' do
+
+    class ErrorJob
+      @queue = :rspec
+      extend Ruote::Resque::Job
+      def self.perform(workitem)
+        workitem['is_resque_awesome'] = true
+        raise 'i am a failure'
+      end
+    end
+
+    let(:workitem) { { 'is_rspec_awesome' => true } }
+    let(:enqued_job) { ::Resque.reserve(Ruote::Resque.configuration.reply_queue) }
+    let(:exception) { RuntimeError.new('i am a failure') }
+    let(:expected_job_args) do
+      [
+        exception.class.name,
+        exception.message,
+        exception.backtrace,
+        workitem
+      ]
+    end
+
+    context 'enqueues a job' do
+
+      before :each do
+        ErrorJob.on_failure_reply_to_ruote(exception, workitem)
+      end
+
+      it 'to resque' do
+        expect(enqued_job.class).to eq ::Resque::Job
+      end
+
+      it 'to the configured reply_queue' do
+        expect(enqued_job.queue).to eq Ruote::Resque.configuration.reply_queue
+      end
+
+      it 'with the workitem and the error as arguments' do
+        expect(enqued_job.args).to eq expected_job_args
+      end
+
+    end
+
+    context 'replies with the mutated workitem' do
+
+      let(:mutated_workitem) { { 'is_rspec_awesome' => true, 'is_resque_awesome' => true } }
+
+      before :each do
+        Resque.inline = true
+      end
+
+      after :each do
+        Resque.inline = false
+      end
+
+      it 'allows the workitem to be mutated' do
+
+        Ruote::Resque::ReplyJob.should_receive(:perform).with(hash_including(mutated_workitem))
+        Resque.enqueue(Job, workitem)
+
+      end
+
+    end
+
+  end
+
+end

data/spec/lib/ruote/resque/participant_registrar_spec.rb

@@ -0,0 +1,52 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+class MyAwesomeJob
+end
+
+describe Ruote::Resque::ParticipantRegistrar do
+
+  context '#participant' do
+
+    let(:mock_dashboard) { Object.new }
+    let(:registrar) { Ruote::Resque::ParticipantRegistrar.new(mock_dashboard) }
+
+    it 'registers the participant to the dashboard' do
+
+      mock_dashboard.should_receive(:register_participant).with('be_awesome', Ruote::Resque::Participant, { :class => MyAwesomeJob, :queue => :rspec })
+      registrar.participant('be_awesome', MyAwesomeJob, :rspec)
+
+    end
+
+    it 'allows more options to be sent' do
+
+      mock_dashboard.should_receive(:register_participant).with('be_awesome', Ruote::Resque::Participant, { :class => MyAwesomeJob, :queue => :rspec, :custom_option => :custom_value })
+      registrar.participant('be_awesome', MyAwesomeJob, :rspec, :custom_option => :custom_value)
+
+    end
+
+  end
+
+  context '#method_missing' do
+
+    let(:mock_dashboard) { Object.new }
+    let(:registrar) { Ruote::Resque::ParticipantRegistrar.new(mock_dashboard) }
+
+    it 'registers the participant to the dashboard' do
+
+      mock_dashboard.should_receive(:register_participant).with('be_awesome', Ruote::Resque::Participant, { :class => MyAwesomeJob, :queue => :rspec })
+      registrar.be_awesome(MyAwesomeJob, :rspec)
+
+    end
+
+    it 'allows more options to be sent' do
+
+      mock_dashboard.should_receive(:register_participant).with('be_awesome', Ruote::Resque::Participant, { :class => MyAwesomeJob, :queue => :rspec, :custom_option => :custom_value })
+      registrar.be_awesome(MyAwesomeJob, :rspec, :custom_option => :custom_value)
+
+    end
+
+  end
+
+end

data/spec/lib/ruote/resque/participant_spec.rb

@@ -0,0 +1,118 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+describe Ruote::Resque::Participant do
+
+  it 'includes Ruote::LocalParticipant' do
+    expect(Ruote::Resque::Participant.ancestors).to include(Ruote::LocalParticipant)
+  end
+
+  it 'does not thread' do
+    expect(Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_queue).do_not_thread).to be_true
+  end
+
+  context '#initialize' do
+
+    it 'takes a job class in options' do
+
+      participant = Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_other_queue)
+      expect(participant.instance_variable_get(:@job_klass)).to eq Class
+
+    end
+
+    it 'takes a job queue in options' do
+
+      participant = Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_other_queue)
+      expect(participant.instance_variable_get(:@job_queue)).to eq :my_other_queue
+
+    end
+
+    it 'validates that jobs have a queue' do
+      expect { Ruote::Resque::Participant.new('class' => Class) }.to raise_error ::Resque::NoQueueError
+    end
+
+    it 'validates that jobs have a class' do
+      expect { Ruote::Resque::Participant.new('class' => '', 'queue' => :my_other_queue) }.to raise_error ::Resque::NoClassError
+    end
+
+  end
+
+  context '#on_workitem' do
+
+    let(:workitem) { { 'rspec_is_awesome' => true } }
+
+    before :each do
+      participant.stub(:workitem).and_return Ruote::Workitem.new(workitem)
+    end
+
+    context 'with forget set to false' do
+
+      let(:participant) { Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_queue) }
+
+      it 'enqueues the given job to Resque' do
+        participant.on_workitem
+        expected_job = { 'class' => 'Class', 'args' => [workitem] }
+        expect(::Resque.pop(:my_queue)).to eq expected_job
+      end
+
+      it 'does not reply to ruote' do
+        participant.should_not_receive(:reply)
+        participant.on_workitem
+      end
+
+    end
+
+    context 'with forget set to true' do
+
+      let(:participant) { Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_queue, 'forget' => true) }
+
+      it 'replies to ruote' do
+        participant.should_receive(:reply)
+        participant.on_workitem
+      end
+
+    end
+
+  end
+
+  context '#on_cancel' do
+
+    let(:workitem) { { 'rspec_is_awesome' => true } }
+    let(:participant) { Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_queue) }
+
+    before :each do
+      participant.stub(:workitem).and_return Ruote::Workitem.new(workitem)
+      participant.stub(:applied_workitem).and_return Ruote::Workitem.new(workitem)
+      participant.on_workitem
+    end
+
+    it 'removes the given job to Resque' do
+      participant.on_cancel
+      expect(::Resque.pop(:my_queue)).to eq nil
+    end
+
+    it 'removes only jobs with the same arguments' do
+      another_participant = Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_queue)
+      another_workitem = { 'im_another_workitem' => true }
+      another_participant.stub(:workitem).and_return Ruote::Workitem.new(another_workitem)
+      another_participant.on_workitem
+
+      participant.on_cancel
+      expect(::Resque.pop(:my_queue)).to eq({ 'class' => 'Class', 'args' => [another_workitem] })
+    end
+
+  end
+
+  context '#encode_workitem' do
+
+    let(:workitem_hash) { { 'rspec_is_awesome' => true } }
+    let(:workitem) { Ruote::Workitem.new(workitem_hash) }
+
+    it 'returns a hash representation of the workitem' do
+      expect(Ruote::Resque::Participant.new('class' => Class, 'queue' => :my_queue).encode_workitem(workitem)).to eq(workitem_hash)
+    end
+
+  end
+
+end