rocketjob 1.3.0 → 2.0.0.rc1

data/lib/rocket_job/plugins/job/state_machine.rb

@@ -0,0 +1,166 @@
+# encoding: UTF-8
+require 'active_support/concern'
+
+module RocketJob
+  module Plugins
+    module Job
+      # State machine for RocketJob::Job
+      module StateMachine
+        extend ActiveSupport::Concern
+
+        included do
+          # State Machine events and transitions
+          #
+          #   :queued -> :running -> :completed
+          #                       -> :paused     -> :running (if started )
+          #                                      -> :queued ( if no started )
+          #                                      -> :aborted
+          #                       -> :failed     -> :aborted
+          #                                      -> :queued
+          #                       -> :aborted
+          #                       -> :queued (when a worker dies)
+          #           -> :aborted
+          aasm column: :state do
+            # Job has been created and is queued for processing ( Initial state )
+            state :queued, initial: true
+
+            # Job is running
+            state :running
+
+            # Job has completed processing ( End state )
+            state :completed
+
+            # Job is temporarily paused and no further processing will be completed
+            # until this job has been resumed
+            state :paused
+
+            # Job failed to process and needs to be manually re-tried or aborted
+            state :failed
+
+            # Job was aborted and cannot be resumed ( End state )
+            state :aborted
+
+            event :start do
+              transitions from: :queued, to: :running
+            end
+
+            event :complete do
+              transitions from: :running, to: :completed
+            end
+
+            event :fail do
+              transitions from: :queued, to: :failed
+              transitions from: :running, to: :failed
+              transitions from: :paused, to: :failed
+            end
+
+            event :retry do
+              transitions from: :failed, to: :queued
+            end
+
+            event :pause do
+              transitions from: :running, to: :paused
+              transitions from: :queued, to: :paused
+            end
+
+            event :resume do
+              transitions from: :paused, to: :running, if: -> { started_at }
+              transitions from: :paused, to: :queued, unless: -> { started_at }
+            end
+
+            event :abort do
+              transitions from: :running, to: :aborted
+              transitions from: :queued, to: :aborted
+              transitions from: :failed, to: :aborted
+              transitions from: :paused, to: :aborted
+            end
+
+            event :requeue do
+              transitions from: :running, to: :queued,
+                if:             -> _worker_name { worker_name == _worker_name },
+                after:          :rocket_job_clear_started_at
+            end
+          end
+          # @formatter:on
+
+          # Define a before and after callback method for each event
+          state_machine_define_event_callbacks(*aasm.state_machine.events.keys)
+
+          before_start :rocket_job_set_started_at
+          before_complete :rocket_job_set_completed_at, :rocket_job_mark_complete
+          before_fail :rocket_job_set_completed_at, :rocket_job_increment_failure_count, :rocket_job_set_exception
+          before_pause :rocket_job_set_completed_at
+          before_abort :rocket_job_set_completed_at
+          before_retry :rocket_job_clear_exception
+          before_resume :rocket_job_clear_completed_at
+          after_complete :rocket_job_destroy_on_complete
+
+          # Pause all running jobs
+          def self.pause_all
+            running.each(&:pause!)
+          end
+
+          # Resume all paused jobs
+          def self.resume_all
+            paused.each(&:resume!)
+          end
+        end
+
+        private
+
+        # Sets the exception child object for this job based on the
+        # supplied Exception instance or message
+        def rocket_job_set_exception(worker_name = nil, exc_or_message = nil)
+          if exc_or_message.is_a?(Exception)
+            self.exception        = JobException.from_exception(exc_or_message)
+            exception.worker_name = worker_name
+          else
+            build_exception(
+              class_name:  'RocketJob::JobException',
+              message:     exc_or_message,
+              backtrace:   [],
+              worker_name: worker_name
+            )
+          end
+        end
+
+        def rocket_job_set_started_at
+          self.started_at = Time.now
+        end
+
+        def rocket_job_mark_complete
+          self.percent_complete = 100
+        end
+
+        def rocket_job_increment_failure_count
+          self.failure_count += 1
+        end
+
+        def rocket_job_clear_exception
+          self.completed_at = nil
+          self.exception    = nil
+          self.worker_name  = nil
+        end
+
+        def rocket_job_set_completed_at
+          self.completed_at = Time.now
+          self.worker_name  = nil
+        end
+
+        def rocket_job_clear_completed_at
+          self.completed_at = nil
+        end
+
+        def rocket_job_clear_started_at
+          self.started_at  = nil
+          self.worker_name = nil
+        end
+
+        def rocket_job_destroy_on_complete
+          destroy if destroy_on_complete && !new_record?
+        end
+      end
+
+    end
+  end
+end

data/lib/rocket_job/plugins/job/worker.rb

@@ -0,0 +1,167 @@
+# encoding: UTF-8
+require 'active_support/concern'
+
+# Worker behavior for a job
+module RocketJob
+  module Plugins
+    module Job
+      module Worker
+        extend ActiveSupport::Concern
+
+        included do
+          # Run this job later
+          #
+          # Saves it to the database for processing later by workers
+          def self.perform_later(*args, &block)
+            if RocketJob::Config.inline_mode
+              perform_now(*args, &block)
+            else
+              job = new(arguments: args)
+              block.call(job) if block
+              job.save!
+              job
+            end
+          end
+
+          # Run this job now.
+          #
+          # The job is not saved to the database since it is processed entriely in memory
+          # As a result before_save and before_destroy callbacks will not be called.
+          # Validations are still called however prior to calling #perform
+          def self.perform_now(*args, &block)
+            job = new(arguments: args)
+            block.call(job) if block
+            job.perform_now
+            job
+          end
+
+          # Returns the next job to work on in priority based order
+          # Returns nil if there are currently no queued jobs, or processing batch jobs
+          #   with records that require processing
+          #
+          # Parameters
+          #   worker_name [String]
+          #     Name of the worker that will be processing this job
+          #
+          #   skip_job_ids [Array<BSON::ObjectId>]
+          #     Job ids to exclude when looking for the next job
+          #
+          # Note:
+          #   If a job is in queued state it will be started
+          def self.rocket_job_next_job(worker_name, skip_job_ids = nil)
+            while (job = rocket_job_retrieve(worker_name, skip_job_ids))
+              case
+              when job.running?
+                # Batch Job
+                return job
+              when job.expired?
+                job.rocket_job_fail_on_exception!(worker_name) { job.destroy }
+                logger.info "Destroyed expired job #{job.class.name}, id:#{job.id}"
+              else
+                job.worker_name = worker_name
+                job.rocket_job_fail_on_exception!(worker_name) { job.start }
+                return job if job.running?
+              end
+            end
+          end
+
+          # Requeues all jobs that were running on worker that died
+          def self.requeue_dead_worker(worker_name)
+            running.each { |job| job.requeue!(worker_name) if job.may_requeue?(worker_name) }
+          end
+
+          # Turn off embedded callbacks. Slow and not used for Jobs
+          embedded_callbacks_off
+        end
+
+        # Runs the job now in the current thread.
+        #
+        # Validations are called prior to running the job.
+        #
+        # The job is not saved and therefore the following callbacks are _not_ called:
+        # * before_save
+        # * after_save
+        # * before_create
+        # * after_create
+        #
+        # Exceptions are _not_ suppressed and should be handled by the caller.
+        def perform_now
+          # Call validations
+          if respond_to?(:validate!)
+            validate!
+          elsif invalid?
+            raise(MongoMapper::DocumentNotValid, self)
+          end
+          worker = RocketJob::Worker.new(name: 'inline')
+          worker.started
+          start if may_start?
+          # Raise exceptions
+          rocket_job_work(worker, true) if running?
+          result
+        end
+
+        def perform(*)
+          raise NotImplementedError
+        end
+
+        # Fail this job in the event of an exception.
+        #
+        # The job is automatically saved only if an exception is raised in the supplied block.
+        #
+        # worker_name: [String]
+        #   Name of the worker on which the exception has occurred
+        #
+        # raise_exceptions: [true|false]
+        #   Re-raise the exception after updating the job
+        #   Default: !RocketJob::Config.inline_mode
+        def rocket_job_fail_on_exception!(worker_name, raise_exceptions = !RocketJob::Config.inline_mode)
+          yield
+        rescue Exception => exc
+          if failed? || !may_fail?
+            self.exception        = JobException.from_exception(exc)
+            exception.worker_name = worker_name
+            save! unless new_record? || destroyed?
+          else
+            if new_record? || destroyed?
+              fail(worker_name, exc)
+            else
+              fail!(worker_name, exc)
+            end
+          end
+          raise exc if raise_exceptions
+        end
+
+        # Works on this job
+        #
+        # Returns [true|false] whether this job should be excluded from the next lookup
+        #
+        # If an exception is thrown the job is marked as failed and the exception
+        # is set in the job itself.
+        #
+        # Thread-safe, can be called by multiple threads at the same time
+        def rocket_job_work(worker, raise_exceptions = !RocketJob::Config.inline_mode)
+          raise(ArgumentError, 'Job must be started before calling #rocket_job_work') unless running?
+          rocket_job_fail_on_exception!(worker.name, raise_exceptions) do
+            run_callbacks :perform do
+              # Allow callbacks to fail, complete or abort the job
+              if running?
+                ret = perform(*arguments)
+                if collect_output?
+                  # Result must be a Hash, if not put it in a Hash
+                  self.result = (ret.is_a?(Hash) || ret.is_a?(BSON::OrderedHash)) ? ret : {result: ret}
+                end
+              end
+            end
+            if new_record? || destroyed?
+              complete if may_complete?
+            else
+              may_complete? ? complete! : save!
+            end
+          end
+          false
+        end
+
+      end
+    end
+  end
+end

data/lib/rocket_job/plugins/restart.rb

@@ -0,0 +1,54 @@
+# encoding: UTF-8
+require 'active_support/concern'
+
+module RocketJob
+  module Plugins
+    # Automatically starts a new instance of this job anytime it fails, aborts, or completes.
+    # Failed jobs are aborted so that they cannot be restarted.
+    # On destroy this job is destroyed without starting a new copy. Abort the job first to get
+    # it to start a new instance before destroying.
+    # Include RocketJob::Plugins::Singleton to prevent multiple copies of a job from running at
+    # the same time.
+    #
+    # Note:
+    # - The job will not be restarted if:
+    #   - A validation fails after cloning this job.
+    #   - The job has expired.
+    module Restart
+      extend ActiveSupport::Concern
+
+      # Attributes to exclude when copying across the attributes to the new instance
+      RESTART_EXCLUDES = %w(_id state created_at started_at completed_at failure_count worker_name percent_complete exception result run_at)
+
+      included do
+        after_abort :rocket_job_restart_new_instance
+        after_complete :rocket_job_restart_new_instance
+        after_fail :rocket_job_restart_abort
+      end
+
+      private
+
+      # Run again in the future, even if this run fails with an exception
+      def rocket_job_restart_new_instance
+        return if expired?
+        attrs = attributes.dup
+        RESTART_EXCLUDES.each { |attr| attrs.delete(attr) }
+
+        # Copy across run_at for future dated jobs
+        attrs['run_at'] = run_at if run_at && (run_at > Time.now)
+        # Allow Singleton to prevent the creation of a new job if one is already running
+        job             = self.class.create(attrs)
+        if job.persisted?
+          logger.info("Started a new job instance: #{job.id}")
+        else
+          logger.info('New job instance not started since one is already active')
+        end
+      end
+
+      def rocket_job_restart_abort
+        new_record? ? abort : abort!
+      end
+
+    end
+  end
+end

data/lib/rocket_job/plugins/singleton.rb

@@ -0,0 +1,26 @@
+# encoding: UTF-8
+require 'active_support/concern'
+
+module RocketJob
+  module Plugins
+    # Prevent more than one instance of this job class from running at a time
+    module Singleton
+      extend ActiveSupport::Concern
+
+      included do
+        # Validation prevents a new job from being saved while one is already running
+        validates_each :state do |record, attr, value|
+          if (record.running? || record.queued? || record.paused?) && record.rocket_job_singleton_active?
+            record.errors.add(attr, "Another instance of #{record.class.name} is already queued or running")
+          end
+        end
+
+        # Returns [true|false] whether another instance of this job is already active
+        def rocket_job_singleton_active?
+          self.class.where(state: [:running, :queued], _id: {'$ne' => id}).exists?
+        end
+      end
+
+    end
+  end
+end

data/lib/rocket_job/plugins/state_machine.rb

@@ -0,0 +1,105 @@
+# encoding: UTF-8
+require 'active_support/concern'
+require 'aasm'
+require 'rocket_job/extensions/aasm'
+
+module RocketJob
+  module Plugins
+    # State machine for RocketJob
+    #
+    # Define before and after callbacks for state machine events
+    #
+    # Example: Supply a method name to call
+    #
+    #  class MyJob < RocketJob::Job
+    #    before_fail :let_me_know
+    #
+    #    def let_me_know
+    #      puts "Oh no, the job has failed with and exception"
+    #    end
+    #  end
+    #
+    # Example: Pass a block
+    #
+    #  class MyJob < RocketJob::Job
+    #    before_fail do
+    #      puts "Oh no, the job has failed with an exception"
+    #    end
+    #  end
+    module StateMachine
+      extend ActiveSupport::Concern
+
+      included do
+        include AASM
+
+        # Adds a :before or :after callback to an event
+        #  state_machine_add_event_callback(:start, :before, :my_method)
+        def self.state_machine_add_event_callback(event_name, action, *methods, &block)
+          raise(ArgumentError, 'Cannot supply both a method name and a block') if (methods.size > 0) && block
+          raise(ArgumentError, 'Must supply either a method name or a block') unless (methods.size > 0) || block
+
+          # TODO Somehow get AASM to support options such as :if and :unless to be consistent with other callbacks
+          # For example:
+          #    before_start :my_callback, unless: :encrypted?
+          #    before_start :my_callback, if: :encrypted?
+          if event = aasm.state_machine.events[event_name]
+            values = Array(event.options[action])
+            code   =
+              if block
+                block
+              else
+                # Validate methods are any of Symbol String Proc
+                methods.each do |method|
+                  unless method.is_a?(Symbol) || method.is_a?(String)
+                    raise(ArgumentError, "#{action}_#{event_name} currently does not support any options. Only Symbol and String method names can be supplied.")
+                  end
+                end
+                methods
+              end
+            action == :before ? values.push(code) : values.unshift(code)
+            event.options[action] = values.flatten.uniq
+          else
+            raise(ArgumentError, "Unknown event: #{event_name.inspect}")
+          end
+        end
+
+        def self.state_machine_define_event_callbacks(*event_names)
+          event_names.each do |event_name|
+            module_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def self.before_#{event_name}(*methods, &block)
+                state_machine_add_event_callback(:#{event_name}, :before, *methods, &block)
+              end
+
+              def self.after_#{event_name}(*methods, &block)
+               state_machine_add_event_callback(:#{event_name}, :after, *methods, &block)
+              end
+            RUBY
+          end
+        end
+
+        # Patch AASM so that save! is called instead of save
+        # So that validations are run before job.requeue! is completed
+        # Otherwise it just fails silently
+        def aasm_write_state(state, name=:default)
+          attr_name = self.class.aasm(name).attribute_name
+          old_value = read_attribute(attr_name)
+          write_attribute(attr_name, state)
+
+          begin
+            if aasm_skipping_validations(name)
+              saved = save(validate: false)
+              write_attribute(attr_name, old_value) unless saved
+              saved
+            else
+              save!
+            end
+          rescue Exception => exc
+            write_attribute(attr_name, old_value)
+            raise(exc)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/rocket_job/version.rb

@@ -1,4 +1,4 @@
 # encoding: UTF-8
 module RocketJob #:nodoc
-  VERSION = '1.3.0'
+  VERSION = '2.0.0.rc1'
 end