good_job 1.2.2 → 1.3.0

data/lib/good_job/job.rb

@@ -1,14 +1,32 @@
 module GoodJob
+  #
+  # Represents a request to perform an +ActiveJob+ job.
+  #
   class Job < ActiveRecord::Base
     include Lockable
 
+    # Raised if something attempts to execute a previously completed Job again.
     PreviouslyPerformedError = Class.new(StandardError)
 
+    # ActiveJob jobs without a +queue_name+ attribute are placed on this queue.
     DEFAULT_QUEUE_NAME = 'default'.freeze
+    # ActiveJob jobs without a +priority+ attribute are given this priority.
     DEFAULT_PRIORITY = 0
 
     self.table_name = 'good_jobs'.freeze
 
+    # Parse a string representing a group of queues into a more readable data
+    # structure.
+    # @return [Hash]
+    #   How to match a given queue. It can have the following keys and values:
+    #   - +{ all: true }+ indicates that all queues match.
+    #   - +{ exclude: Array<String> }+ indicates the listed queue names should
+    #     not match.
+    #   - +{ include: Array<String> }+ indicates the listed queue names should
+    #     match.
+    # @example
+    #   GoodJob::Job.queue_parser('-queue1,queue2')
+    #   => { exclude: [ 'queue1', 'queue2' ] }
     def self.queue_parser(string)
       string = string.presence || '*'
 
@@ -28,6 +46,10 @@ module GoodJob
       end
     end
 
+    # Get Jobs that have not yet been completed.
+    # @!method unfinished
+    # @!scope class
+    # @return [ActiveRecord::Relation]
     scope :unfinished, (lambda do
       if column_names.include?('finished_at')
         where(finished_at: nil)
@@ -36,9 +58,42 @@ module GoodJob
         nil
       end
     end)
+
+    # Get Jobs that are not scheduled for a later time than now (i.e. jobs that
+    # are not scheduled or scheduled for earlier than the current time).
+    # @!method only_scheduled
+    # @!scope class
+    # @return [ActiveRecord::Relation]
     scope :only_scheduled, -> { where(arel_table['scheduled_at'].lteq(Time.current)).or(where(scheduled_at: nil)) }
+
+    # Order jobs by priority (highest priority first).
+    # @!method priority_ordered
+    # @!scope class
+    # @return [ActiveRecord::Relation]
     scope :priority_ordered, -> { order('priority DESC NULLS LAST') }
+
+    # Get Jobs were completed before the given timestamp. If no timestamp is
+    # provided, get all jobs that have been completed. By default, GoodJob
+    # deletes jobs after they are completed and this will find no jobs.
+    # However, if you have changed {GoodJob.preserve_job_records}, this may
+    # find completed Jobs.
+    # @!method finished(timestamp = nil)
+    # @!scope class
+    # @param timestamp (Float)
+    #   Get jobs that finished before this time (in epoch time).
+    # @return [ActiveRecord::Relation]
     scope :finished, ->(timestamp = nil) { timestamp ? where(arel_table['finished_at'].lteq(timestamp)) : where.not(finished_at: nil) }
+
+    # Get Jobs on queues that match the given queue string.
+    # @!method queue_string(string)
+    # @!scope class
+    # @param string [String]
+    #   A string expression describing what queues to select. See
+    #   {Job.queue_parser} or
+    #   {file:README.md#optimize-queues-threads-and-processes} for more details
+    #   on the format of the string. Note this only handles individual
+    #   semicolon-separated segments of that string format.
+    # @return [ActiveRecord::Relation]
     scope :queue_string, (lambda do |string|
       parsed = queue_parser(string)
 
@@ -51,6 +106,31 @@ module GoodJob
       end
     end)
 
+    # 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)
+
+    # Finds the next eligible Job, acquire an advisory lock related to it, and
+    # executes the job.
+    # @return [Array<(GoodJob::Job, Object, Exception)>, 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
@@ -67,6 +147,15 @@ module GoodJob
       [good_job, result, error] if good_job
     end
 
+    # Places an ActiveJob job on a queue by creating a new {Job} record.
+    # @param active_job [ActiveJob::Base]
+    #   The job to enqueue.
+    # @param scheduled_at [Float]
+    #   Epoch timestamp when the job should be executed.
+    # @param create_with_advisory_lock [Boolean]
+    #   Whether to establish a lock on the {Job} record after it is created.
+    # @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|
@@ -87,57 +176,58 @@ module GoodJob
       good_job
     end
 
-    def perform(destroy_after: !GoodJob.preserve_job_records, reperform_on_standard_error: GoodJob.reperform_jobs_on_standard_error)
+    # Execute the ActiveJob job this {Job} represents.
+    # @return [Array<(Object, Exception)>]
+    #   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
-      result = nil
-      rescued_error = nil
-      error = nil
 
       self.performed_at = Time.current
-      save! unless destroy_after
-
-      params = serialized_params.merge(
-        "provider_job_id" => id
-      )
-
-      begin
-        ActiveSupport::Notifications.instrument("perform_job.good_job", { good_job: self, process_id: GoodJob::CurrentExecution.process_id, thread_name: GoodJob::CurrentExecution.thread_name }) do
-          result = ActiveJob::Base.execute(params)
-        end
-      rescue StandardError => e
-        rescued_error = e
-      end
+      save! if GoodJob.preserve_job_records
 
-      retry_or_discard_error = GoodJob::CurrentExecution.error_on_retry ||
-                               GoodJob::CurrentExecution.error_on_discard
+      result, unhandled_error = execute
 
-      if rescued_error
-        error = rescued_error
-      elsif result.is_a?(Exception)
-        error = result
+      result_error = nil
+      if result.is_a?(Exception)
+        result_error = result
         result = nil
-      elsif retry_or_discard_error
-        error = retry_or_discard_error
       end
 
-      error_message = "#{error.class}: #{error.message}" if error
-      self.error = error_message
+      job_error = unhandled_error ||
+                  result_error ||
+                  GoodJob::CurrentExecution.error_on_retry ||
+                  GoodJob::CurrentExecution.error_on_discard
+
+      self.error = "#{job_error.class}: #{job_error.message}" if job_error
 
-      if rescued_error && reperform_on_standard_error
+      if unhandled_error && GoodJob.retry_on_unhandled_error
         save!
-      else
+      elsif GoodJob.preserve_job_records == true || (unhandled_error && GoodJob.preserve_job_records == :on_unhandled_error)
         self.finished_at = Time.current
-
-        if destroy_after
-          destroy!
-        else
-          save!
-        end
+        save!
+      else
+        destroy!
       end
 
-      [result, error]
+      [result, job_error]
+    end
+
+    private
+
+    def execute
+      params = serialized_params.merge(
+        "provider_job_id" => id
+      )
+
+      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]
+      end
+    rescue StandardError => e
+      [nil, e]
     end
   end
 end

data/lib/good_job/lockable.rb

@@ -1,10 +1,33 @@
 module GoodJob
+  #
+  # Adds Postgres advisory locking capabilities to an ActiveRecord record.
+  # For details on advisory locks, see the Postgres documentation:
+  # - {https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS Advisory Locks Overview}
+  # - {https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS Advisory Locks Functions}
+  #
+  # @example Add this concern to a +MyRecord+ class:
+  #   class MyRecord < ActiveRecord::Base
+  #     include Lockable
+  #
+  #     def my_method
+  #       ...
+  #     end
+  #   end
+  #
   module Lockable
     extend ActiveSupport::Concern
 
+    # Indicates an advisory lock is already held on a record by another
+    # database session.
     RecordAlreadyAdvisoryLockedError = Class.new(StandardError)
 
     included do
+      # Attempt to acquire an advisory lock on the selected records and
+      # return only those records for which a lock could be acquired.
+      # @!method advisory_lock
+      # @!scope class
+      # @return [ActiveRecord::Relation]
+      #   A relation selecting only the records that were locked.
       scope :advisory_lock, (lambda do
         original_query = self
 
@@ -13,35 +36,92 @@ module GoodJob
 
         query = cte_table.project(cte_table[:id])
                   .with(composed_cte)
-                  .where(Arel.sql(sanitize_sql_for_conditions(["pg_try_advisory_lock(('x'||substr(md5(:table_name || \"#{cte_table.name}\".\"#{primary_key}\"::text), 1, 16))::bit(64)::bigint)", { table_name: table_name }])))
+                  .where(Arel.sql(sanitize_sql_for_conditions(["pg_try_advisory_lock(('x' || substr(md5(:table_name || #{connection.quote_table_name(cte_table.name)}.#{quoted_primary_key}::text), 1, 16))::bit(64)::bigint)", { table_name: table_name }])))
 
         limit = original_query.arel.ast.limit
         query.limit = limit.value if limit.present?
 
-        unscoped.where(arel_table[:id].in(query)).merge(original_query.only(:order))
+        unscoped.where(arel_table[primary_key].in(query)).merge(original_query.only(:order))
       end)
 
+      # Joins the current query with Postgres's +pg_locks+ table (it provides
+      # data about existing locks) such that each row in the main query joins
+      # to all the advisory locks associated with that row.
+      #
+      # For details on +pg_locks+, see
+      # {https://www.postgresql.org/docs/current/view-pg-locks.html}.
+      # @!method joins_advisory_locks
+      # @!scope class
+      # @return [ActiveRecord::Relation]
+      # @example Get the records that have a session awaiting a lock:
+      #   MyLockableRecord.joins_advisory_locks.where("pg_locks.granted = ?", false)
       scope :joins_advisory_locks, (lambda do
         join_sql = <<~SQL
           LEFT JOIN pg_locks ON pg_locks.locktype = 'advisory'
             AND pg_locks.objsubid = 1
-            AND pg_locks.classid = ('x'||substr(md5(:table_name || "#{table_name}"."#{primary_key}"::text), 1, 16))::bit(32)::int
-            AND pg_locks.objid = (('x'||substr(md5(:table_name || "#{table_name}"."#{primary_key}"::text), 1, 16))::bit(64) << 32)::bit(32)::int
+            AND pg_locks.classid = ('x' || substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(32)::int
+            AND pg_locks.objid = (('x' || substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(64) << 32)::bit(32)::int
         SQL
 
         joins(sanitize_sql_for_conditions([join_sql, { table_name: table_name }]))
       end)
 
+      # Find records that do not have an advisory lock on them.
+      # @!method advisory_unlocked
+      # @!scope class
+      # @return [ActiveRecord::Relation]
       scope :advisory_unlocked, -> { joins_advisory_locks.where(pg_locks: { locktype: nil }) }
+
+      # Find records that have an advisory lock on them.
+      # @!method advisory_locked
+      # @!scope class
+      # @return [ActiveRecord::Relation]
       scope :advisory_locked, -> { joins_advisory_locks.where.not(pg_locks: { locktype: nil }) }
+
+      # Find records with advisory locks owned by the current Postgres
+      # session/connection.
+      # @!method advisory_locked
+      # @!scope class
+      # @return [ActiveRecord::Relation]
       scope :owns_advisory_locked, -> { joins_advisory_locks.where('"pg_locks"."pid" = pg_backend_pid()') }
 
+      # @!attribute [r] create_with_advisory_lock
+      # @return [Boolean]
+      # Whether an advisory lock should be acquired in the same transaction
+      # that created the record.
+      #
+      # This helps prevent another thread or database session from acquiring a
+      # lock on the record between the time you create it and the time you
+      # request a lock, since other sessions will not be able to see the new
+      # record until the transaction that creates it is completed (at which
+      # point you have already acquired the lock).
+      #
+      # @example
+      #   record = MyLockableRecord.create(create_with_advisory_lock: true)
+      #   record.advisory_locked?
+      #   => true
       attr_accessor :create_with_advisory_lock
 
       after_create -> { advisory_lock }, if: :create_with_advisory_lock
     end
 
     class_methods do
+      # Acquires an advisory lock on the selected record(s) and safely releases
+      # it after the passed block is completed. The block will be passed an
+      # array of the locked records as its first argument.
+      #
+      # Note that this will not block and wait for locks to be acquired.
+      # Instead, it will acquire a lock on all the selected records that it
+      # can (as in {Lockable.advisory_lock}) and only pass those that could be
+      # locked to the block.
+      #
+      # @yield [Array<Lockable>] the records that were successfully locked.
+      # @return [Object] the result of the block.
+      #
+      # @example Work on the first two +MyLockableRecord+ objects that could be locked:
+      #   MyLockableRecord.order(created_at: :asc).limit(2).with_advisory_lock do |record|
+      #     do_something_with record
+      #   end
       def with_advisory_lock
         raise ArgumentError, "Must provide a block" unless block_given?
 
@@ -54,25 +134,51 @@ module GoodJob
       end
     end
 
+    # Acquires an advisory lock on this record if it is not already locked by
+    # another database session. Be careful to ensure you release the lock when
+    # you are done with {#advisory_unlock} (or {#advisory_unlock!} to release
+    # all remaining locks).
+    # @return [Boolean] whether the lock was acquired.
     def advisory_lock
       where_sql = <<~SQL
-        pg_try_advisory_lock(('x'||substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
+        pg_try_advisory_lock(('x' || substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
       SQL
       self.class.unscoped.where(where_sql, { table_name: self.class.table_name, id: send(self.class.primary_key) }).exists?
     end
 
+    # Releases an advisory lock on this record if it is locked by this database
+    # session. Note that advisory locks stack, so you must call
+    # {#advisory_unlock} and {#advisory_lock} the same number of times.
+    # @return [Boolean] whether the lock was released.
     def advisory_unlock
       where_sql = <<~SQL
-        pg_advisory_unlock(('x'||substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
+        pg_advisory_unlock(('x' || substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
       SQL
       self.class.unscoped.where(where_sql, { table_name: self.class.table_name, id: send(self.class.primary_key) }).exists?
     end
 
+    # Acquires an advisory lock on this record or raises
+    # {RecordAlreadyAdvisoryLockedError} if it is already locked by another
+    # database session.
+    # @raise [RecordAlreadyAdvisoryLockedError]
+    # @return [Boolean] +true+
     def advisory_lock!
       result = advisory_lock
       result || raise(RecordAlreadyAdvisoryLockedError)
     end
 
+    # Acquires an advisory lock on this record and safely releases it after the
+    # passed block is completed. If the record is locked by another database
+    # session, this raises {RecordAlreadyAdvisoryLockedError}.
+    #
+    # @yield Nothing
+    # @return [Object] The result of the block.
+    #
+    # @example
+    #   record = MyLockableRecord.first
+    #   record.with_advisory_lock do
+    #     do_something_with record
+    #   end
     def with_advisory_lock
       raise ArgumentError, "Must provide a block" unless block_given?
 
@@ -82,14 +188,21 @@ module GoodJob
       advisory_unlock unless $ERROR_INFO.is_a? RecordAlreadyAdvisoryLockedError
     end
 
+    # Tests whether this record has an advisory lock on it.
+    # @return [Boolean]
     def advisory_locked?
       self.class.unscoped.advisory_locked.where(id: send(self.class.primary_key)).exists?
     end
 
+    # Tests whether this record is locked by the current database session.
+    # @return [Boolean]
     def owns_advisory_lock?
       self.class.unscoped.owns_advisory_locked.where(id: send(self.class.primary_key)).exists?
     end
 
+    # Releases all advisory locks on the record that are held by the current
+    # database session.
+    # @return [void]
     def advisory_unlock!
       advisory_unlock while advisory_locked?
     end

data/lib/good_job/log_subscriber.rb

@@ -1,6 +1,22 @@
 module GoodJob
+  #
+  # Listens to GoodJob notifications and logs them.
+  #
+  # Each method corresponds to the name of a notification. For example, when
+  # the {Scheduler} shuts down, it sends a notification named
+  # +"scheduler_shutdown.good_job"+ and the {#scheduler_shutdown} method will
+  # be called here. See the
+  # {https://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html ActiveSupport::LogSubscriber}
+  # documentation for more.
+  #
   class LogSubscriber < ActiveSupport::LogSubscriber
+    # @!group Notifications
+
+    # @!macro notification_responder
+    #   Responds to the +$0.good_job+ notification.
+    #   @return [void]
     def create(event)
+      # FIXME: This method does not match any good_job notifications.
       good_job = event.payload[:good_job]
 
       debug do
@@ -8,7 +24,8 @@ module GoodJob
       end
     end
 
-    def timer_task_finished(event)
+    # @macro notification_responder
+    def finished_timer_task(event)
       exception = event.payload[:error]
       return unless exception
 
@@ -17,7 +34,8 @@ module GoodJob
       end
     end
 
-    def job_finished(event)
+    # @macro notification_responder
+    def finished_job_task(event)
       exception = event.payload[:error]
       return unless exception
 
@@ -26,6 +44,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_create_pools(event)
       max_threads = event.payload[:max_threads]
       poll_interval = event.payload[:poll_interval]
@@ -37,6 +56,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_shutdown_start(event)
       process_id = event.payload[:process_id]
 
@@ -45,6 +65,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_shutdown(event)
       process_id = event.payload[:process_id]
 
@@ -53,6 +74,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_restart_pools(event)
       process_id = event.payload[:process_id]
 
@@ -61,6 +83,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def perform_job(event)
       good_job = event.payload[:good_job]
       process_id = event.payload[:process_id]
@@ -71,12 +94,14 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def notifier_listen(_event)
       info do
         "Notifier subscribed with LISTEN"
       end
     end
 
+    # @macro notification_responder
     def notifier_notified(event)
       payload = event.payload[:payload]
 
@@ -85,6 +110,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def notifier_notify_error(event)
       error = event.payload[:error]
 
@@ -93,12 +119,14 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def notifier_unlisten(_event)
       info do
         "Notifier unsubscribed with UNLISTEN"
       end
     end
 
+    # @macro notification_responder
     def cleanup_preserved_jobs(event)
       timestamp = event.payload[:timestamp]
       deleted_records_count = event.payload[:deleted_records_count]
@@ -108,11 +136,34 @@ module GoodJob
       end
     end
 
+    # @!endgroup
+
+    # Get the logger associated with this {LogSubscriber} instance.
+    # @return [Logger]
+    def logger
+      GoodJob::LogSubscriber.logger
+    end
+
     class << self
+      # Tracks all loggers that {LogSubscriber} is writing to. You can write to
+      # multiple logs by appending to this array. After updating it, you should
+      # usually call {LogSubscriber.reset_logger} to make sure they are all
+      # written to.
+      #
+      # Defaults to {GoodJob.logger}.
+      # @return [Array<Logger>]
+      # @example Write to STDOUT and to a file:
+      #   GoodJob::LogSubscriber.loggers << ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT))
+      #   GoodJob::LogSubscriber.loggers << ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new("log/my_logs.log"))
+      #   GoodJob::LogSubscriber.reset_logger
       def loggers
         @_loggers ||= [GoodJob.logger]
       end
 
+      # Represents all the loggers attached to {LogSubscriber} with a single
+      # logging interface. Writing to this logger is a shortcut for writing to
+      # each of the loggers in {LogSubscriber.loggers}.
+      # @return [Logger]
       def logger
         @_logger ||= begin
                       logger = Logger.new(StringIO.new)
@@ -123,17 +174,22 @@ module GoodJob
                     end
       end
 
+      # Reset {LogSubscriber.logger} and force it to rebuild a new shortcut to
+      # all the loggers in {LogSubscriber.loggers}. You should usually call
+      # this after modifying the {LogSubscriber.loggers} array.
+      # @return [void]
       def reset_logger
         @_logger = nil
       end
     end
 
-    def logger
-      GoodJob::LogSubscriber.logger
-    end
-
     private
 
+    # Add "GoodJob" plus any specified tags to every
+    # {ActiveSupport::TaggedLogging} logger in {LogSubscriber.loggers}. Tags
+    # are only applicable inside the block passed to this method.
+    # @yield [void]
+    # @return [void]
     def tag_logger(*tags, &block)
       tags = tags.dup.unshift("GoodJob").compact
 
@@ -152,6 +208,14 @@ module GoodJob
       end.call
     end
 
+    # Ensure that the standard logging methods include "GoodJob" as a tag and
+    # that they include a second argument allowing callers to specify ad-hoc
+    # tags to include in the message.
+    #
+    # For example, to include the tag "ForFunsies" on an +info+ message:
+    #
+    #     self.info("Some message", tags: ["ForFunsies"])
+    #
     %w(info debug warn error fatal unknown).each do |level|
       class_eval <<-METHOD, __FILE__, __LINE__ + 1
         def #{level}(progname = nil, tags: [], &block)