good_job 2.4.0 → 2.6.0

data/lib/good_job/active_job_job.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+module GoodJob
+  # ActiveRecord model that represents an +ActiveJob+ job.
+  # There is not a table in the database whose discrete rows represents "Jobs".
+  # The +good_jobs+ table is a table of individual {GoodJob::Execution}s that share the same +active_job_id+.
+  # A single row from the +good_jobs+ table of executions is fetched to represent an ActiveJobJob
+  # Parent class can be configured with +GoodJob.active_record_parent_class+.
+  # @!parse
+  #   class ActiveJob < ActiveRecord::Base; end
+  class ActiveJobJob < Object.const_get(GoodJob.active_record_parent_class)
+    include GoodJob::Lockable
+
+    # Raised when an inappropriate action is applied to a Job based on its state.
+    ActionForStateMismatchError = Class.new(StandardError)
+    # Raised when an action requires GoodJob to be the ActiveJob Queue Adapter but GoodJob is not.
+    AdapterNotGoodJobError = Class.new(StandardError)
+    # Attached to a Job's Execution when the Job is discarded.
+    DiscardJobError = Class.new(StandardError)
+
+    self.table_name = 'good_jobs'
+    self.primary_key = 'active_job_id'
+    self.advisory_lockable_column = 'active_job_id'
+
+    has_many :executions, -> { order(created_at: :asc) }, class_name: 'GoodJob::Execution', foreign_key: 'active_job_id'
+
+    # Only the most-recent unretried execution represents a "Job"
+    default_scope { where(retried_good_job_id: nil) }
+
+    # Get Jobs with given class name
+    # @!method job_class
+    # @!scope class
+    # @param string [String]
+    #   Execution class name
+    # @return [ActiveRecord::Relation]
+    scope :job_class, ->(job_class) { where("serialized_params->>'job_class' = ?", job_class) }
+
+    # First execution will run in the future
+    scope :scheduled, -> { where(finished_at: nil).where('COALESCE(scheduled_at, created_at) > ?', DateTime.current).where("(serialized_params->>'executions')::integer < 2") }
+    # Execution errored, will run in the future
+    scope :retried, -> { where(finished_at: nil).where('COALESCE(scheduled_at, created_at) > ?', DateTime.current).where("(serialized_params->>'executions')::integer > 1") }
+    # Immediate/Scheduled time to run has passed, waiting for an available thread run
+    scope :queued, -> { where(finished_at: nil).where('COALESCE(scheduled_at, created_at) <= ?', DateTime.current).joins_advisory_locks.where(pg_locks: { locktype: nil }) }
+    # Advisory locked and executing
+    scope :running, -> { where(finished_at: nil).joins_advisory_locks.where.not(pg_locks: { locktype: nil }) }
+    # Completed executing successfully
+    scope :finished, -> { where.not(finished_at: nil).where(error: nil) }
+    # Errored but will not be retried
+    scope :discarded, -> { where.not(finished_at: nil).where.not(error: nil) }
+
+    # Get Jobs in display order with optional keyset pagination.
+    # @!method display_all(after_scheduled_at: nil, after_id: nil)
+    # @!scope class
+    # @param after_scheduled_at [DateTime, String, nil]
+    #   Display records scheduled after this time for keyset pagination
+    # @param after_id [Numeric, String, nil]
+    #   Display records after this ID for keyset pagination
+    # @return [ActiveRecord::Relation]
+    scope :display_all, (lambda do |after_scheduled_at: nil, after_id: nil|
+      query = order(Arel.sql('COALESCE(scheduled_at, created_at) DESC, id DESC'))
+      if after_scheduled_at.present? && after_id.present?
+        query = query.where(Arel.sql('(COALESCE(scheduled_at, created_at), id) < (:after_scheduled_at, :after_id)'), after_scheduled_at: after_scheduled_at, after_id: after_id)
+      elsif after_scheduled_at.present?
+        query = query.where(Arel.sql('(COALESCE(scheduled_at, created_at)) < (:after_scheduled_at)'), after_scheduled_at: after_scheduled_at)
+      end
+      query
+    end)
+
+    # The job's ActiveJob UUID
+    # @return [String]
+    def id
+      active_job_id
+    end
+
+    # The ActiveJob job class, as a string
+    # @return [String]
+    def job_class
+      serialized_params['job_class']
+    end
+
+    # The status of the Job, based on the state of its most recent execution.
+    # There are 3 buckets of non-overlapping statuses:
+    #   1. The job will be executed
+    #     - queued: The job will execute immediately when an execution thread becomes available.
+    #     - scheduled: The job is scheduled to execute in the future.
+    #     - retried: The job previously errored on execution and will be re-executed in the future.
+    #   2. The job is being executed
+    #     - running: the job is actively being executed by an execution thread
+    #   3. The job will not execute
+    #     - finished: The job executed successfully
+    #     - discarded: The job previously errored on execution and will not be re-executed in the future.
+    #
+    # @return [Symbol]
+    def status
+      execution = head_execution
+      if execution.finished_at.present?
+        if execution.error.present?
+          :discarded
+        else
+          :finished
+        end
+      elsif (execution.scheduled_at || execution.created_at) > DateTime.current
+        if execution.serialized_params.fetch('executions', 0) > 1
+          :retried
+        else
+          :scheduled
+        end
+      elsif running?
+        :running
+      else
+        :queued
+      end
+    end
+
+    # This job's most recent {Execution}
+    # @param reload [Booelan] whether to reload executions
+    # @return [Execution]
+    def head_execution(reload: false)
+      executions.reload if reload
+      executions.load # memoize the results
+      executions.last
+    end
+
+    # This job's initial/oldest {Execution}
+    # @return [Execution]
+    def tail_execution
+      executions.first
+    end
+
+    # The number of times this job has been executed, according to ActiveJob's serialized state.
+    # @return [Numeric]
+    def executions_count
+      aj_count = head_execution.serialized_params.fetch('executions', 0)
+      # The execution count within serialized_params is not updated
+      # once the underlying execution has been executed.
+      if status.in? [:discarded, :finished, :running]
+        aj_count + 1
+      else
+        aj_count
+      end
+    end
+
+    # The number of times this job has been executed, according to the number of GoodJob {Execution} records.
+    # @return [Numeric]
+    def preserved_executions_count
+      executions.size
+    end
+
+    # The most recent error message.
+    # If the job has been retried, the error will be fetched from the previous {Execution} record.
+    # @return [String]
+    def recent_error
+      head_execution.error || executions[-2]&.error
+    end
+
+    # Tests whether the job is being executed right now.
+    # @return [Boolean]
+    def running?
+      # Avoid N+1 Query: `.joins_advisory_locks.select('good_jobs.*', 'pg_locks.locktype AS locktype')`
+      if has_attribute?(:locktype)
+        self['locktype'].present?
+      else
+        advisory_locked?
+      end
+    end
+
+    # Retry a job that has errored and been discarded.
+    # This action will create a new job {Execution} record.
+    # @return [ActiveJob::Base]
+    def retry_job
+      with_advisory_lock do
+        execution = head_execution(reload: true)
+        active_job = execution.active_job
+
+        raise AdapterNotGoodJobError unless active_job.class.queue_adapter.is_a? GoodJob::Adapter
+        raise ActionForStateMismatchError unless status == :discarded
+
+        # Update the executions count because the previous execution will not have been preserved
+        # Do not update `exception_executions` because that comes from rescue_from's arguments
+        active_job.executions = (active_job.executions || 0) + 1
+
+        new_active_job = nil
+        GoodJob::CurrentThread.within do |current_thread|
+          current_thread.execution = execution
+
+          execution.class.transaction(joinable: false, requires_new: true) do
+            new_active_job = active_job.retry_job(wait: 0, error: error)
+            execution.save
+          end
+        end
+        new_active_job
+      end
+    end
+
+    # Discard a job so that it will not be executed further.
+    # This action will add a {DiscardJobError} to the job's {Execution} and mark it as finished.
+    # @return [void]
+    def discard_job(message)
+      with_advisory_lock do
+        raise ActionForStateMismatchError unless status.in? [:scheduled, :queued, :retried]
+
+        execution = head_execution(reload: true)
+        active_job = execution.active_job
+
+        job_error = GoodJob::ActiveJobJob::DiscardJobError.new(message)
+
+        update_execution = proc do
+          execution.update(
+            finished_at: Time.current,
+            error: [job_error.class, GoodJob::Execution::ERROR_MESSAGE_SEPARATOR, job_error.message].join
+          )
+        end
+
+        if active_job.respond_to?(:instrument)
+          active_job.send :instrument, :discard, error: job_error, &update_execution
+        else
+          update_execution.call
+        end
+      end
+    end
+
+    # Reschedule a scheduled job so that it executes immediately (or later) by the next available execution thread.
+    # @param scheduled_at [DateTime, Time] When to reschedule the job
+    # @return [void]
+    def reschedule_job(scheduled_at = Time.current)
+      with_advisory_lock do
+        raise ActionForStateMismatchError unless status.in? [:scheduled, :queued, :retried]
+
+        execution = head_execution(reload: true)
+        execution.update(scheduled_at: scheduled_at)
+      end
+    end
+
+    # Utility method to determine which execution record is used to represent this job
+    # @return [String]
+    def _execution_id
+      attributes['id']
+    end
+
+    # Utility method to test whether this job's underlying attributes represents its most recent execution.
+    # @return [Boolean]
+    def _head?
+      _execution_id == head_execution(reload: true).id
+    end
+  end
+end

data/lib/good_job/adapter.rb

@@ -38,7 +38,7 @@ module GoodJob
         @notifier.recipients << [@scheduler, :create_thread]
         @poller.recipients << [@scheduler, :create_thread]
 
-        @cron_manager = GoodJob::CronManager.new(@configuration.cron, start_on_initialize: Rails.application.initialized?) if @configuration.enable_cron?
+        @cron_manager = GoodJob::CronManager.new(@configuration.cron_entries, start_on_initialize: Rails.application.initialized?) if @configuration.enable_cron?
       end
     end
 
@@ -64,10 +64,12 @@ module GoodJob
 
       if execute_inline?
         begin
-          execution.perform
+          result = execution.perform
         ensure
           execution.advisory_unlock
         end
+
+        raise result.unhandled_error if result.unhandled_error
       else
         job_state = { queue_name: execution.queue_name }
         job_state[:scheduled_at] = execution.scheduled_at if execution.scheduled_at

data/lib/good_job/cli.rb

@@ -91,7 +91,9 @@ module GoodJob
       scheduler = GoodJob::Scheduler.from_configuration(configuration, warm_cache_on_initialize: true)
       notifier.recipients << [scheduler, :create_thread]
       poller.recipients << [scheduler, :create_thread]
-      cron_manager = GoodJob::CronManager.new(configuration.cron, start_on_initialize: true) if configuration.enable_cron?
+
+      cron_manager = GoodJob::CronManager.new(configuration.cron_entries, start_on_initialize: true) if configuration.enable_cron?
+
       @stop_good_job_executable = false
       %w[INT TERM].each do |signal|
         trap(signal) { @stop_good_job_executable = true }

data/lib/good_job/configuration.rb

@@ -157,7 +157,7 @@ module GoodJob
     alias enable_cron? enable_cron
 
     def cron
-      env_cron = JSON.parse(ENV['GOOD_JOB_CRON']) if ENV['GOOD_JOB_CRON'].present?
+      env_cron = JSON.parse(ENV['GOOD_JOB_CRON'], symbolize_names: true) if ENV['GOOD_JOB_CRON'].present?
 
       options[:cron] ||
         rails_config[:cron] ||
@@ -165,6 +165,10 @@ module GoodJob
         {}
     end
 
+    def cron_entries
+      cron.map { |cron_key, params| GoodJob::CronEntry.new(params.merge(key: cron_key)) }
+    end
+
     # Number of seconds to preserve jobs when using the +good_job cleanup_preserved_jobs+ CLI command.
     # This configuration is only used when {GoodJob.preserve_job_records} is +true+.
     # @return [Integer]

data/lib/good_job/cron_entry.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+require "concurrent/hash"
+require "concurrent/scheduled_task"
+require "fugit"
+
+module GoodJob # :nodoc:
+  #
+  # A CronEntry represents a single scheduled item's properties.
+  #
+  class CronEntry
+    include ActiveModel::Model
+
+    attr_reader :params
+
+    def self.all(configuration: nil)
+      configuration ||= GoodJob::Configuration.new({})
+      configuration.cron_entries
+    end
+
+    def self.find(key, configuration: nil)
+      all(configuration: configuration).find { |entry| entry.key == key.to_sym }.tap do |cron_entry|
+        raise ActiveRecord::RecordNotFound unless cron_entry
+      end
+    end
+
+    def initialize(params = {})
+      @params = params
+
+      raise ArgumentError, "Invalid cron format: '#{cron}'" unless fugit.instance_of?(Fugit::Cron)
+    end
+
+    def key
+      params.fetch(:key)
+    end
+
+    alias id key
+    alias to_param key
+
+    def job_class
+      params.fetch(:class)
+    end
+
+    def cron
+      params.fetch(:cron)
+    end
+
+    def set
+      params[:set]
+    end
+
+    def args
+      params[:args]
+    end
+
+    def description
+      params[:description]
+    end
+
+    def next_at
+      fugit.next_time.to_t
+    end
+
+    def schedule
+      fugit.original
+    end
+
+    def fugit
+      @_fugit ||= Fugit.parse(cron)
+    end
+
+    def jobs
+      GoodJob::ActiveJobJob.where(cron_key: key)
+    end
+
+    def last_at
+      return if last_job.blank?
+
+      if GoodJob::ActiveJobJob.column_names.include?('cron_at')
+        (last_job.cron_at || last_job.created_at).localtime
+      else
+        last_job.created_at
+      end
+    end
+
+    def enqueue(cron_at = nil)
+      GoodJob::CurrentThread.within do |current_thread|
+        current_thread.cron_key = key
+        current_thread.cron_at = cron_at
+
+        job_class.constantize.set(set_value).perform_later(*args_value)
+      end
+    rescue ActiveRecord::RecordNotUnique
+      false
+    end
+
+    def last_job
+      if GoodJob::ActiveJobJob.column_names.include?('cron_at')
+        jobs.order("cron_at DESC NULLS LAST").first
+      else
+        jobs.order(created_at: :asc).last
+      end
+    end
+
+    def display_properties
+      {
+        key: key,
+        class: job_class,
+        cron: schedule,
+        set: display_property(set),
+        args: display_property(args),
+        description: display_property(description),
+      }
+    end
+
+    private
+
+    def set_value
+      value = set || {}
+      value.respond_to?(:call) ? value.call : value
+    end
+
+    def args_value
+      value = args || []
+      value.respond_to?(:call) ? value.call : value
+    end
+
+    def display_property(value)
+      case value
+      when NilClass
+        "None"
+      when Proc
+        "Lambda/Callable"
+      else
+        value
+      end
+    end
+  end
+end

data/lib/good_job/cron_manager.rb

@@ -11,7 +11,7 @@ module GoodJob # :nodoc:
     # @!attribute [r] instances
     #   @!scope class
     #   List of all instantiated CronManagers in the current process.
-    #   @return [Array<GoodJob::CronManagers>, nil]
+    #   @return [Array<GoodJob::CronManager>, nil]
     cattr_reader :instances, default: [], instance_reader: false
 
     # Task observer for cron task
@@ -26,13 +26,13 @@ module GoodJob # :nodoc:
 
     # Execution configuration to be scheduled
     # @return [Hash]
-    attr_reader :schedules
+    attr_reader :cron_entries
 
-    # @param schedules [Hash]
+    # @param cron_entries [Array<CronEntry>]
     # @param start_on_initialize [Boolean]
-    def initialize(schedules = {}, start_on_initialize: false)
+    def initialize(cron_entries = [], start_on_initialize: false)
       @running = false
-      @schedules = schedules
+      @cron_entries = cron_entries
       @tasks = Concurrent::Hash.new
 
       self.class.instances << self
@@ -42,9 +42,11 @@ module GoodJob # :nodoc:
 
     # Schedule tasks that will enqueue jobs based on their schedule
     def start
-      ActiveSupport::Notifications.instrument("cron_manager_start.good_job", cron_jobs: @schedules) do
+      ActiveSupport::Notifications.instrument("cron_manager_start.good_job", cron_entries: cron_entries) do
         @running = true
-        schedules.each_key { |cron_key| create_task(cron_key) }
+        cron_entries.each do |cron_entry|
+          create_task(cron_entry)
+        end
       end
     end
 
@@ -78,36 +80,20 @@ module GoodJob # :nodoc:
     end
 
     # Enqueues a scheduled task
-    # @param cron_key [Symbol, String] the key within the schedule to use
-    def create_task(cron_key)
-      schedule = @schedules[cron_key]
-      return false if schedule.blank?
-
-      fugit = Fugit::Cron.parse(schedule.fetch(:cron))
-      delay = [(fugit.next_time - Time.current).to_f, 0].max
-
-      future = Concurrent::ScheduledTask.new(delay, args: [self, cron_key]) do |thr_scheduler, thr_cron_key|
+    # @param cron_entry [CronEntry] the CronEntry object to schedule
+    def create_task(cron_entry)
+      cron_at = cron_entry.next_at
+      delay = [(cron_at - Time.current).to_f, 0].max
+      future = Concurrent::ScheduledTask.new(delay, args: [self, cron_entry, cron_at]) do |thr_scheduler, thr_cron_entry, thr_cron_at|
         # Re-schedule the next cron task before executing the current task
-        thr_scheduler.create_task(thr_cron_key)
-
-        CurrentThread.reset
-        CurrentThread.cron_key = thr_cron_key
+        thr_scheduler.create_task(thr_cron_entry)
 
         Rails.application.executor.wrap do
-          schedule = thr_scheduler.schedules.fetch(thr_cron_key).with_indifferent_access
-          job_class = schedule.fetch(:class).constantize
-
-          job_set_value = schedule.fetch(:set, {})
-          job_set = job_set_value.respond_to?(:call) ? job_set_value.call : job_set_value
-
-          job_args_value = schedule.fetch(:args, [])
-          job_args = job_args_value.respond_to?(:call) ? job_args_value.call : job_args_value
-
-          job_class.set(job_set).perform_later(*job_args)
+          cron_entry.enqueue(thr_cron_at)
         end
       end
 
-      @tasks[cron_key] = future
+      @tasks[cron_entry.key] = future
       future.add_observer(self.class, :task_observer)
       future.execute
     end

data/lib/good_job/current_thread.rb

@@ -5,6 +5,21 @@ module GoodJob
   # Thread-local attributes for passing values from Instrumentation.
   # (Cannot use ActiveSupport::CurrentAttributes because ActiveJob resets it)
   module CurrentThread
+    # Resettable accessors for thread-local values.
+    ACCESSORS = %i[
+      cron_at
+      cron_key
+      error_on_discard
+      error_on_retry
+      execution
+    ].freeze
+
+    # @!attribute [rw] cron_at
+    #   @!scope class
+    #   Cron At
+    #   @return [DateTime, nil]
+    thread_mattr_accessor :cron_at
+
     # @!attribute [rw] cron_key
     #   @!scope class
     #   Cron Key
@@ -30,12 +45,20 @@ module GoodJob
     thread_mattr_accessor :execution
 
     # Resets attributes
+    # @param [Hash] values to assign
     # @return [void]
-    def self.reset
-      self.cron_key = nil
-      self.execution = nil
-      self.error_on_discard = nil
-      self.error_on_retry = nil
+    def self.reset(values = {})
+      ACCESSORS.each do |accessor|
+        send("#{accessor}=", values[accessor])
+      end
+    end
+
+    # Exports values to hash
+    # @return [Hash]
+    def self.to_h
+      ACCESSORS.each_with_object({}) do |accessor, hash|
+        hash[accessor] = send(accessor)
+      end
     end
 
     # @return [String] UUID of the currently executing GoodJob::Execution
@@ -52,5 +75,15 @@ module GoodJob
     def self.thread_name
       (Thread.current.name || Thread.current.object_id).to_s
     end
+
+    # Wrap the yielded block with CurrentThread values and reset after the block
+    # @yield [self]
+    # @return [void]
+    def self.within
+      original_values = to_h
+      yield(self)
+    ensure
+      reset(original_values)
+    end
   end
 end