Merge pull request #60 from rainforestapp/RF-30285-add-qc-job-callbacks

[RF-30285] Add QC job callbacks

Author: CChanHY

README.md

@@ -124,6 +124,59 @@ class Jobs::NoTransaction < QueueClassicPlus::Base
 end
 ```
 
+
+#### Callbacks
+
+Jobs support the following callbacks:
+```
+before_enqueue
+after_enqueue
+before_perform
+after_perform
+```
+
+- `enqueue` callbacks are called when the job is initially enqueued. Caveats:
+  - not called on retries
+  - not called when scheduled in the future (i.e. `Job.enqueue_perform_in`)
+  - still called if enqueuing fails because a job with `lock!` is already enqueued. 
+- `perform` callbacks are called any time the job is picked up and run by a worker, including retries and jobs scheduled in the future.
+
+Callbacks can either be implemented by providing a method to be called:
+
+```ruby
+class Jobs::WithCallbackMethods < QueueClassicPlus::Base
+  before_enqueue :before_enqueue_method
+
+  @queue = :low
+
+  def self.before_enqueue_method(*args)
+    # ...
+  end
+
+  def self.perform(user_id)
+    # ...
+  end
+end
+```
+
+or by providing a block:
+
+```ruby
+class Jobs::WithCallbackBlocks < QueueClassicPlus::Base
+  before_enqueue do |*args|
+    # ...
+  end
+
+  @queue = :low
+
+  def self.perform(user_id)
+    # ...
+  end
+end
+```
+
+The `args` passed to the callback method/block will be the same as the arguments passed to `QueueClassicPlus::Base.do` and `QueueClassicPlus::Base.perform`. 
+
 ## Advanced configuration
 
 If you want to log exceptions in your favorite exception tracker. You can configured it like so:

lib/queue_classic_plus/base.rb

@@ -136,6 +136,22 @@ def self.transaction(options = {}, &block)
       end
     end
 
+    def self.before_enqueue(callback_method = nil, &block)
+      define_callback(:enqueue, :before, callback_method, &block)
+    end
+
+    def self.after_enqueue(callback_method = nil, &block)
+      define_callback(:enqueue, :after, callback_method, &block)
+    end
+
+    def self.before_perform(callback_method = nil, &block)
+      define_callback(:perform, :before, callback_method, &block)
+    end
+
+    def self.after_perform(callback_method = nil, &block)
+      define_callback(:perform, :after, callback_method, &block)
+    end
+
     # Debugging
     def self.list
       q = "SELECT * FROM queue_classic_jobs WHERE q_name = '#{@queue}'"
@@ -165,5 +181,26 @@ def self.deserialized(args)
     def self.execute(sql, *args)
       QC.default_conn_adapter.execute(sql, *args)
     end
+
+    def self.define_callback(name, type, callback_method, &_block)
+      singleton_class.prepend(
+        Module.new do |callback_module|
+          callback_module.define_method(name) do |*args|
+            callback_args = args
+              if name == :enqueue
+                callback_args = callback_args.drop(1) # Class/method is the first argument. Callbacks don't need that.
+              end
+
+              if type == :before
+                block_given? ? yield(*callback_args) : send(callback_method, *callback_args)
+              end
+              super(*args)
+              if type == :after
+                block_given? ? yield(*callback_args) : send(callback_method, *callback_args)
+              end
+          end
+        end
+      )
+    end
   end
 end

lib/queue_classic_plus/version.rb

@@ -1,3 +1,3 @@
 module QueueClassicPlus
-  VERSION = '4.0.0.alpha18'.freeze
+  VERSION = '4.0.0.alpha19'.freeze
 end

spec/base_spec.rb

@@ -184,6 +184,172 @@ def self.perform(foo, bar)
         subject._perform(42, true)
       end
     end
+
+    context "with callbacks defined" do
+      subject do
+        Class.new(QueueClassicPlus::Base) do
+          @queue = :test
+
+          before_enqueue :before_enqueue_method
+          after_enqueue :after_enqueue_method
+
+          before_perform :before_perform_method
+          after_perform :after_perform_method
+
+          def self.before_enqueue_method(*_args); end;
+          def self.after_enqueue_method(*_args); end;
+          def self.before_perform_method(*_args); end;
+          def self.after_perform_method(*_args); end;
+
+          def self.perform(*_args); end;
+        end
+      end
+
+      it "passes enqueue arguments to callbacks" do
+        expect(subject).to receive(:before_enqueue_method).with("enqueue_argument").once
+        expect(subject).to receive(:after_enqueue_method).with("enqueue_argument").once
+
+        subject.do("enqueue_argument")
+      end
+
+      it "passes perform arguments to callbacks" do
+        expect(subject).to receive(:before_perform_method).with("perform_argument").once
+        expect(subject).to receive(:after_perform_method).with("perform_argument").once
+
+        subject.perform("perform_argument")
+      end
+
+      context "when enqueued" do
+        it "calls the enqueue callback methods" do
+          expect(subject).to receive(:before_enqueue_method).once
+          expect(subject).to receive(:after_enqueue_method).once
+
+          subject.do
+        end
+
+        it "does not call the perform callbacks" do
+          expect(subject).to_not receive(:before_perform_method)
+          expect(subject).to_not receive(:after_perform_method)
+
+          subject.do
+        end
+      end
+
+      context "when perform" do
+        it "calls the perform callback methods" do
+          expect(subject).to receive(:before_perform_method).once
+          expect(subject).to receive(:after_perform_method).once
+
+          subject.perform
+        end
+
+        it "does not call the enqueue callbacks" do
+          expect(subject).to_not receive(:before_enqueue_method)
+          expect(subject).to_not receive(:after_enqueue_method)
+
+          subject.perform
+        end
+
+        context "when perform fails" do
+          subject do
+            Class.new(QueueClassicPlus::Base) do
+              @queue = :test
+
+              before_perform :before_perform_method
+              after_perform :after_perform_method
+
+              def self.before_perform_method(*_args); end;
+              def self.after_perform_method(*_args); end;
+
+              def self.perform(*_args)
+                raise StandardError
+              end
+            end
+          end
+
+          it "does not call after callbacks" do
+            expect(subject).to receive(:before_perform_method).once
+            expect(subject).to_not receive(:after_perform_method)
+
+            begin
+              subject.perform
+            rescue StandardError
+            end
+          end
+        end
+      end
+
+      context "when callback defined multiple times" do
+        subject do
+          Class.new(QueueClassicPlus::Base) do
+            @queue = :test
+
+            before_enqueue :before_enqueue_method_1
+            before_enqueue :before_enqueue_method_2
+            before_enqueue :before_enqueue_method_3
+
+            def self.before_enqueue_method_1(*_args); end;
+            def self.before_enqueue_method_2(*_args); end;
+            def self.before_enqueue_method_3(*_args); end;
+
+            def self.perform(*_args); end;
+          end
+        end
+
+        it "calls each callback" do
+          expect(subject).to receive(:before_enqueue_method_1).once
+          expect(subject).to receive(:before_enqueue_method_2).once
+          expect(subject).to receive(:before_enqueue_method_3).once
+
+          subject.do
+        end
+      end
+    end
+
+    context "with callback blocks defined" do
+      subject do
+        Class.new(QueueClassicPlus::Base) do
+          @queue = :test
+          class_variable_set(:@@block_result, [])
+
+          before_enqueue do |*_args|
+            class_variable_get(:@@block_result).append("before_enqueue_block")
+          end
+          after_enqueue do |*_args|
+            class_variable_get(:@@block_result).append("after_enqueue_block")
+          end
+
+          before_perform do |*_args|
+            class_variable_get(:@@block_result).append("before_perform_block")
+          end
+          after_perform do |*_args|
+            class_variable_get(:@@block_result).append("after_perform_block")
+          end
+
+          def self.perform; end;
+        end
+      end
+
+      context "when enqueued" do
+        it "calls the enqueue callback blocks" do
+          subject.do
+
+          expect(subject.class_variable_get(:@@block_result)).to eq(
+            %w(before_enqueue_block after_enqueue_block)
+          )
+        end
+      end
+
+      context "when perform" do
+        it "calls the perform callback blocks" do
+          subject.perform
+
+          expect(subject.class_variable_get(:@@block_result)).to eq(
+            %w(before_perform_block after_perform_block)
+          )
+        end
+      end
+    end
   end
 
   describe ".librato_key" do