good_job 1.7.0 → 1.9.2

data/lib/good_job/cli.rb

@@ -15,9 +15,21 @@ module GoodJob
     # Requiring this loads the application's configuration and classes.
     RAILS_ENVIRONMENT_RB = File.expand_path("config/environment.rb")
 
-    # @!visibility private
-    def self.exit_on_failure?
-      true
+    class << self
+      # Whether the CLI is running from the executable
+      # @return [Boolean, nil]
+      attr_accessor :within_exe
+      alias within_exe? within_exe
+
+      # Whether to log to STDOUT
+      # @return [Boolean, nil]
+      attr_accessor :log_to_stdout
+      alias log_to_stdout? log_to_stdout
+
+      # @!visibility private
+      def exit_on_failure?
+        true
+      end
     end
 
     # @!macro thor.desc
@@ -53,6 +65,10 @@ module GoodJob
                   type: :numeric,
                   banner: 'COUNT',
                   desc: "Maximum number of scheduled jobs to cache in memory (env var: GOOD_JOB_MAX_CACHE, default: 10000)"
+    method_option :shutdown_timeout,
+                  type: :numeric,
+                  banner: 'SECONDS',
+                  desc: "Number of seconds to wait for jobs to finish when shutting down before stopping the thread. (env var: GOOD_JOB_SHUTDOWN_TIMEOUT, default: -1 (forever))"
     method_option :daemonize,
                   type: :boolean,
                   desc: "Run as a background daemon (default: false)"
@@ -67,7 +83,7 @@ module GoodJob
 
       notifier = GoodJob::Notifier.new
       poller = GoodJob::Poller.new(poll_interval: configuration.poll_interval)
-      scheduler = GoodJob::Scheduler.from_configuration(configuration)
+      scheduler = GoodJob::Scheduler.from_configuration(configuration, warm_cache_on_initialize: true)
       notifier.recipients << [scheduler, :create_thread]
       poller.recipients << [scheduler, :create_thread]
 
@@ -81,9 +97,8 @@ module GoodJob
         break if @stop_good_job_executable || scheduler.shutdown? || notifier.shutdown?
       end
 
-      notifier.shutdown
-      poller.shutdown
-      scheduler.shutdown
+      executors = [notifier, poller, scheduler]
+      GoodJob._shutdown_all(executors, timeout: configuration.shutdown_timeout)
     end
 
     default_task :start
@@ -133,7 +148,7 @@ module GoodJob
       # Rails or from the application can be set up here.
       def set_up_application!
         require RAILS_ENVIRONMENT_RB
-        return unless defined?(GOOD_JOB_LOG_TO_STDOUT) && GOOD_JOB_LOG_TO_STDOUT && !ActiveSupport::Logger.logger_outputs_to?(GoodJob.logger, $stdout)
+        return unless GoodJob::CLI.log_to_stdout? && !ActiveSupport::Logger.logger_outputs_to?(GoodJob.logger, $stdout)
 
         GoodJob::LogSubscriber.loggers << ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new($stdout))
         GoodJob::LogSubscriber.reset_logger

data/lib/good_job/configuration.rb

@@ -5,6 +5,8 @@ module GoodJob
   # set options to get the final values for each option.
   #
   class Configuration
+    # Valid execution modes.
+    EXECUTION_MODES = [:async, :async_server, :external, :inline].freeze
     # Default number of threads to use per {Scheduler}
     DEFAULT_MAX_THREADS = 5
     # Default number of seconds between polls for jobs
@@ -13,6 +15,8 @@ module GoodJob
     DEFAULT_MAX_CACHE = 10000
     # Default number of seconds to preserve jobs for {CLI#cleanup_preserved_jobs}
     DEFAULT_CLEANUP_PRESERVED_JOBS_BEFORE_SECONDS_AGO = 24 * 60 * 60
+    # Default to always wait for jobs to finish for {Adapter#shutdown}
+    DEFAULT_SHUTDOWN_TIMEOUT = -1
 
     # The options that were explicitly set when initializing +Configuration+.
     # @return [Hash]
@@ -33,40 +37,30 @@ module GoodJob
       @env = env
     end
 
+    def validate!
+      raise ArgumentError, "GoodJob execution mode must be one of #{EXECUTION_MODES.join(', ')}. It was '#{execution_mode}' which is not valid." unless execution_mode.in?(EXECUTION_MODES)
+    end
+
     # Specifies how and where jobs should be executed. See {Adapter#initialize}
     # for more details on possible values.
-    #
-    # When running inside a Rails app, you may want to use
-    # {#rails_execution_mode}, which takes the current Rails environment into
-    # account when determining the final value.
-    #
-    # @param default [Symbol]
-    #   Value to use if none was specified in the configuration.
     # @return [Symbol]
-    def execution_mode(default: :external)
-      if defined?(GOOD_JOB_WITHIN_CLI) && GOOD_JOB_WITHIN_CLI
-        :external
-      elsif options[:execution_mode]
-        options[:execution_mode]
-      elsif rails_config[:execution_mode]
-        rails_config[:execution_mode]
-      elsif env['GOOD_JOB_EXECUTION_MODE'].present?
-        env['GOOD_JOB_EXECUTION_MODE'].to_sym
-      else
-        default
-      end
-    end
+    def execution_mode
+      @_execution_mode ||= begin
+        mode = if GoodJob::CLI.within_exe?
+                 :external
+               else
+                 options[:execution_mode] ||
+                   rails_config[:execution_mode] ||
+                   env['GOOD_JOB_EXECUTION_MODE']
+               end
 
-    # Like {#execution_mode}, but takes the current Rails environment into
-    # account (e.g. in the +test+ environment, it falls back to +:inline+).
-    # @return [Symbol]
-    def rails_execution_mode
-      if execution_mode(default: nil)
-        execution_mode
-      elsif Rails.env.development? || Rails.env.test?
-        :inline
-      else
-        :external
+        if mode
+          mode.to_sym
+        elsif Rails.env.development? || Rails.env.test?
+          :inline
+        else
+          :external
+        end
       end
     end
 
@@ -77,10 +71,10 @@ module GoodJob
     def max_threads
       (
         options[:max_threads] ||
-        rails_config[:max_threads] ||
-        env['GOOD_JOB_MAX_THREADS'] ||
-        env['RAILS_MAX_THREADS'] ||
-        DEFAULT_MAX_THREADS
+          rails_config[:max_threads] ||
+          env['GOOD_JOB_MAX_THREADS'] ||
+          env['RAILS_MAX_THREADS'] ||
+          DEFAULT_MAX_THREADS
       ).to_i
     end
 
@@ -103,9 +97,9 @@ module GoodJob
     def poll_interval
       (
         options[:poll_interval] ||
-        rails_config[:poll_interval] ||
-        env['GOOD_JOB_POLL_INTERVAL'] ||
-        DEFAULT_POLL_INTERVAL
+          rails_config[:poll_interval] ||
+          env['GOOD_JOB_POLL_INTERVAL'] ||
+          DEFAULT_POLL_INTERVAL
       ).to_i
     end
 
@@ -122,15 +116,27 @@ module GoodJob
       ).to_i
     end
 
+    # The number of seconds to wait for jobs to finish when shutting down
+    # before stopping the thread. +-1+ is forever.
+    # @return [Numeric]
+    def shutdown_timeout
+      (
+        options[:shutdown_timeout] ||
+          rails_config[:shutdown_timeout] ||
+          env['GOOD_JOB_SHUTDOWN_TIMEOUT'] ||
+          DEFAULT_SHUTDOWN_TIMEOUT
+      ).to_f
+    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]
     def cleanup_preserved_jobs_before_seconds_ago
       (
         options[:before_seconds_ago] ||
-        rails_config[:cleanup_preserved_jobs_before_seconds_ago] ||
-        env['GOOD_JOB_CLEANUP_PRESERVED_JOBS_BEFORE_SECONDS_AGO'] ||
-        DEFAULT_CLEANUP_PRESERVED_JOBS_BEFORE_SECONDS_AGO
+          rails_config[:cleanup_preserved_jobs_before_seconds_ago] ||
+          env['GOOD_JOB_CLEANUP_PRESERVED_JOBS_BEFORE_SECONDS_AGO'] ||
+          DEFAULT_CLEANUP_PRESERVED_JOBS_BEFORE_SECONDS_AGO
       ).to_i
     end
 

data/lib/good_job/execution_result.rb

@@ -0,0 +1,20 @@
+module GoodJob
+  # Stores the results of job execution
+  class ExecutionResult
+    # @return [Object, nil]
+    attr_reader :value
+    # @return [Exception, nil]
+    attr_reader :handled_error
+    # @return [Exception, nil]
+    attr_reader :unhandled_error
+
+    # @param value [Object, nil]
+    # @param handled_error [Exception, nil]
+    # @param unhandled_error [Exception, nil]
+    def initialize(value:, handled_error: nil, unhandled_error: nil)
+      @value = value
+      @handled_error = handled_error
+      @unhandled_error = unhandled_error
+    end
+  end
+end

data/lib/good_job/job.rb

@@ -1,8 +1,9 @@
 module GoodJob
-  #
-  # Represents a request to perform an +ActiveJob+ job.
-  #
-  class Job < ActiveRecord::Base
+  # ActiveRecord model that represents an +ActiveJob+ job.
+  # Parent class can be configured with +GoodJob.active_record_parent_class+.
+  # @!parse
+  #   class Job < ActiveRecord::Base; end
+  class Job < Object.const_get(GoodJob.active_record_parent_class)
     include Lockable
 
     # Raised if something attempts to execute a previously completed Job again.
@@ -15,8 +16,11 @@ module GoodJob
 
     self.table_name = 'good_jobs'.freeze
 
+    attr_readonly :serialized_params
+
     # Parse a string representing a group of queues into a more readable data
     # structure.
+    # @param string [String] Queue string
     # @return [Hash]
     #   How to match a given queue. It can have the following keys and values:
     #   - +{ all: true }+ indicates that all queues match.
@@ -132,29 +136,26 @@ module GoodJob
 
     # Finds the next eligible Job, acquire an advisory lock related to it, and
     # executes the job.
-    # @return [Array<(GoodJob::Job, Object, Exception)>, nil]
+    # @return [ExecutionResult, nil]
     #   If a job was executed, returns an array with the {Job} record, the
     #   return value for the job's +#perform+ method, and the exception the job
     #   raised, if any (if the job raised, then the second array entry will be
     #   +nil+). If there were no jobs to execute, returns +nil+.
     def self.perform_with_advisory_lock
-      good_job = nil
-      result = nil
-      error = nil
-
       unfinished.priority_ordered.only_scheduled.limit(1).with_advisory_lock do |good_jobs|
         good_job = good_jobs.first
         # TODO: Determine why some records are fetched without an advisory lock at all
         break unless good_job&.executable?
 
-        result, error = good_job.perform
+        good_job.perform
       end
-
-      [good_job, result, error] if good_job
     end
 
     # Fetches the scheduled execution time of the next eligible Job(s).
-    # @return [Array<(DateTime)>]
+    # @param after [DateTime]
+    # @param limit [Integer]
+    # @param now_limit [Integer, nil]
+    # @return [Array<DateTime>]
     def self.next_scheduled_at(after: nil, limit: 100, now_limit: nil)
       query = advisory_unlocked.unfinished.schedule_ordered
 
@@ -180,7 +181,6 @@ module GoodJob
     # @return [Job]
     #   The new {Job} instance representing the queued ActiveJob job.
     def self.enqueue(active_job, scheduled_at: nil, create_with_advisory_lock: false)
-      good_job = nil
       ActiveSupport::Notifications.instrument("enqueue_job.good_job", { active_job: active_job, scheduled_at: scheduled_at, create_with_advisory_lock: create_with_advisory_lock }) do |instrument_payload|
         good_job = GoodJob::Job.new(
           queue_name: active_job.queue_name.presence || DEFAULT_QUEUE_NAME,
@@ -194,49 +194,37 @@ module GoodJob
 
         good_job.save!
         active_job.provider_job_id = good_job.id
-      end
 
-      good_job
+        good_job
+      end
     end
 
     # Execute the ActiveJob job this {Job} represents.
-    # @return [Array<(Object, Exception)>]
+    # @return [ExecutionResult]
     #   An array of the return value of the job's +#perform+ method and the
     #   exception raised by the job, if any. If the job completed successfully,
     #   the second array entry (the exception) will be +nil+ and vice versa.
     def perform
       raise PreviouslyPerformedError, 'Cannot perform a job that has already been performed' if finished_at
 
-      GoodJob::CurrentExecution.reset
-
       self.performed_at = Time.current
       save! if GoodJob.preserve_job_records
 
-      result, unhandled_error = execute
-
-      result_error = nil
-      if result.is_a?(Exception)
-        result_error = result
-        result = nil
-      end
-
-      job_error = unhandled_error ||
-                  result_error ||
-                  GoodJob::CurrentExecution.error_on_retry ||
-                  GoodJob::CurrentExecution.error_on_discard
+      result = execute
 
+      job_error = result.handled_error || result.unhandled_error
       self.error = "#{job_error.class}: #{job_error.message}" if job_error
 
-      if unhandled_error && GoodJob.retry_on_unhandled_error
+      if result.unhandled_error && GoodJob.retry_on_unhandled_error
         save!
-      elsif GoodJob.preserve_job_records == true || (unhandled_error && GoodJob.preserve_job_records == :on_unhandled_error)
+      elsif GoodJob.preserve_job_records == true || (result.unhandled_error && GoodJob.preserve_job_records == :on_unhandled_error)
         self.finished_at = Time.current
         save!
       else
         destroy!
       end
 
-      [result, job_error]
+      result
     end
 
     # Tests whether this job is safe to be executed by this thread.
@@ -247,16 +235,26 @@ module GoodJob
 
     private
 
+    # @return [GoodJob::ExecutionResult]
     def execute
       params = serialized_params.merge(
         "provider_job_id" => id
       )
 
+      GoodJob::CurrentExecution.reset
       ActiveSupport::Notifications.instrument("perform_job.good_job", { good_job: self, process_id: GoodJob::CurrentExecution.process_id, thread_name: GoodJob::CurrentExecution.thread_name }) do
-        [ActiveJob::Base.execute(params), nil]
+        value = ActiveJob::Base.execute(params)
+
+        if value.is_a?(Exception)
+          handled_error = value
+          value = nil
+        end
+        handled_error ||= GoodJob::CurrentExecution.error_on_retry || GoodJob::CurrentExecution.error_on_discard
+
+        ExecutionResult.new(value: value, handled_error: handled_error)
+      rescue StandardError => e
+        ExecutionResult.new(value: nil, unhandled_error: e)
       end
-    rescue StandardError => e
-      [nil, e]
     end
   end
 end

data/lib/good_job/job_performer.rb

@@ -51,9 +51,10 @@ module GoodJob
     end
 
     # The Returns timestamps of when next tasks may be available.
-    # @param count [Integer] number of timestamps to return
-    # @param count [DateTime, Time, nil] jobs scheduled after this time
-    # @return [Array<(Time, Timestamp)>, nil]
+    # @param after [DateTime, Time, nil] future jobs scheduled after this time
+    # @param limit [Integer] number of future timestamps to return
+    # @param now_limit [Integer] number of past timestamps to return
+    # @return [Array<(Time, DateTime)>, nil]
     def next_at(after: nil, limit: nil, now_limit: nil)
       job_query.next_scheduled_at(after: after, limit: limit, now_limit: now_limit)
     end

data/lib/good_job/lockable.rb

@@ -143,7 +143,7 @@ module GoodJob
       def supports_cte_materialization_specifiers?
         return @_supports_cte_materialization_specifiers if defined?(@_supports_cte_materialization_specifiers)
 
-        @_supports_cte_materialization_specifiers = ActiveRecord::Base.connection.postgresql_version >= 120000
+        @_supports_cte_materialization_specifiers = connection.postgresql_version >= 120000
       end
     end
 
@@ -158,7 +158,7 @@ module GoodJob
         WHERE pg_try_advisory_lock(('x'||substr(md5($1 || $2::text), 1, 16))::bit(64)::bigint)
       SQL
       binds = [[nil, self.class.table_name], [nil, send(self.class.primary_key)]]
-      ActiveRecord::Base.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Lock', binds).any?
+      self.class.connection.exec_query(pg_or_jdbc_query(query), 'GoodJob::Lockable Advisory Lock', binds).any?
     end
 
     # Releases an advisory lock on this record if it is locked by this database

data/lib/good_job/multi_scheduler.rb

@@ -1,16 +1,16 @@
 module GoodJob
   # Delegates the interface of a single {Scheduler} to multiple Schedulers.
   class MultiScheduler
-    # @return [array<Scheduler>] List of the scheduler delegates
+    # @return [Array<Scheduler>] List of the scheduler delegates
     attr_reader :schedulers
 
     def initialize(schedulers)
       @schedulers = schedulers
     end
 
-    # Delegates to {Scheduler#shutdown}.
-    def shutdown(wait: true)
-      schedulers.each { |s| s.shutdown(wait: wait) }
+    # Delegates to {Scheduler#running?}.
+    def running?
+      schedulers.all?(&:running?)
     end
 
     # Delegates to {Scheduler#shutdown?}.
@@ -18,9 +18,14 @@ module GoodJob
       schedulers.all?(&:shutdown?)
     end
 
+    # Delegates to {Scheduler#shutdown}.
+    def shutdown(timeout: -1)
+      GoodJob._shutdown_all(schedulers, timeout: timeout)
+    end
+
     # Delegates to {Scheduler#restart}.
-    def restart(wait: true)
-      schedulers.each { |s| s.restart(wait: wait) }
+    def restart(timeout: -1)
+      GoodJob._shutdown_all(schedulers, :restart, timeout: timeout)
     end
 
     # Delegates to {Scheduler#create_thread}.
@@ -39,7 +44,7 @@ module GoodJob
 
       if results.any?
         true
-      elsif results.any? { |result| result == false }
+      elsif results.any?(false)
         false
       else # rubocop:disable Style/EmptyElse
         nil