rocketjob 6.3.2 → 7.0.0

data/lib/rocket_job/batch/throttle_running_workers.rb

@@ -36,7 +36,11 @@ module RocketJob
 
         validates :throttle_running_workers, numericality: {greater_than_or_equal_to: 0}, allow_nil: true
 
-        define_batch_throttle :throttle_running_workers_exceeded?, filter: :throttle_filter_id
+        define_batch_throttle :throttle_running_workers_exceeded?,
+                              filter:      :throttle_filter_id,
+                              description: lambda { |job, *|
+                                "Throttled: maximum of #{job.throttle_running_workers} running workers reached"
+                              }
       end
 
       private

data/lib/rocket_job/batch/throttle_windows.rb

@@ -43,7 +43,9 @@ module RocketJob
         # Duration in seconds of the secondary window.
         field :secondary_duration, type: Integer, class_attribute: true, user_editable: true, copy_on_restart: true
 
-        define_batch_throttle :throttle_windows_exceeded?, filter: :throttle_filter_id
+        define_batch_throttle :throttle_windows_exceeded?,
+                              filter:      :throttle_filter_id,
+                              description: "Throttled: outside of its processing window"
 
         validates_each :primary_schedule, :secondary_schedule do |record, attr, value|
           record.errors.add(attr, "Invalid #{attr}: #{value.inspect}") if value && !Fugit::Cron.new(value)
@@ -62,7 +64,7 @@ module RocketJob
 
       def throttle_outside_window?(schedule, duration)
         cron = Fugit::Cron.new(schedule)
-        time = Time.now.utc + 1
+        time = Time.now.getutc + 1
         # Add 1 second since right now could be the very beginning of the processing window.
         previous_time = cron.previous_time(time).to_utc_time
         previous_time + duration < time

data/lib/rocket_job/batch/worker.rb

@@ -69,7 +69,7 @@ module RocketJob
       # Note: The slice will be removed from processing when this method completes
       #
       # @deprecated Please open a ticket if you need this behavior.
-      def work_first_slice(&block)
+      def work_first_slice(&)
         raise "#work_first_slice can only be called from within before_batch callbacks" unless sub_state == :before
 
         # TODO: Make these settings configurable
@@ -89,7 +89,7 @@ module RocketJob
 
         # TODO: Persist that the first slice is being processed by this worker
         slice.start
-        rocket_job_process_slice(slice, &block)
+        rocket_job_process_slice(slice, &)
       end
 
       # Returns [Array<ActiveWorker>] All workers actively working on this job
@@ -111,15 +111,52 @@ module RocketJob
       end
 
       def rocket_job_batch_throttled?(slice, worker)
-        filter = self.class.rocket_job_batch_throttles.matching_filter(self, slice)
-        return false unless filter
+        throttle = self.class.rocket_job_batch_throttles.matching_throttle(self, slice)
+        unless throttle
+          rocket_job_clear_throttled
+          return false
+        end
 
         # Restore retrieved slice so that other workers can process it later.
         slice.set(worker_name: nil, state: :queued, started_at: nil)
-        worker.add_to_current_filter(filter)
+        worker.add_to_current_filter(throttle.extract_filter(self, slice))
+        rocket_job_set_throttled(throttle.extract_description(self, slice))
         true
       end
 
+      # Record why this batch job's slices are being throttled, for visibility in
+      # Mission Control.
+      #
+      # Unlike a simple job, a running batch job document is shared by every worker
+      # and is deliberately not written on each poll (see Worker#find_and_assign_job).
+      # The reason is therefore persisted with a guarded conditional update so the
+      # shared document is only written when the reason actually changes, not on
+      # every throttled poll.
+      def rocket_job_set_throttled(reason)
+        return if throttled_by == reason
+
+        self.class.with(write: {w: 1}) do |query|
+          query.where(id: id, state: :running, :throttled_by.ne => reason).
+            update_all("$set" => {throttled_by: reason, throttled_at: Time.now})
+        end
+        self.throttled_by = reason
+      end
+
+      # Clear the throttle reason once slices are flowing again.
+      #
+      # Gated on the in-memory value so a worker that never throttled this job
+      # issues no database round trip per slice; only a worker that previously set
+      # a reason clears it, with a guarded update to avoid a redundant write.
+      def rocket_job_clear_throttled
+        return if throttled_by.nil?
+
+        self.class.with(write: {w: 1}) do |query|
+          query.where(id: id, :throttled_by.ne => nil).
+            update_all("$unset" => {throttled_by: "", throttled_at: ""})
+        end
+        self.throttled_by = nil
+      end
+
       # Process a single slice from Mongo
       # Once the slice has been successfully processed it will be removed from the input collection
       # Returns [Integer] the number of records successfully processed
@@ -151,7 +188,7 @@ module RocketJob
           if slice.processing_record_number.to_i > 1
             append = true
             logger.info("Resuming previously incomplete slice from record number #{slice.processing_record_number}")
-            slice.records[slice.processing_record_number - 1..-1]
+            slice.records[(slice.processing_record_number - 1)..]
           else
             # Reprocess all records in this slice.
             slice.processing_record_number = 0
@@ -162,8 +199,11 @@ module RocketJob
         RocketJob::Sliced::Writer::Output.collect(self, input_slice: slice, append: append) do |writer|
           records.each do |record|
             slice.processing_record_number += 1
-            SemanticLogger.named_tagged(record: slice.current_record_number) do
-              writer << rocket_job_batch_perform(slice, record, &block)
+            # `current_record_number` reads Mongoid fields, so compute it once per
+            # record and reuse it for both the log tag and `#perform`.
+            record_number = slice.current_record_number
+            SemanticLogger.named_tagged(record: record_number) do
+              writer << rocket_job_batch_perform(slice, record, record_number, &block)
               count += 1
             end
           end
@@ -172,8 +212,8 @@ module RocketJob
       end
 
       # Perform a single record within the current slice.
-      def rocket_job_batch_perform(slice, record)
-        @rocket_job_record_number = slice.current_record_number
+      def rocket_job_batch_perform(slice, record, record_number = slice.current_record_number)
+        @rocket_job_record_number = record_number
 
         return block_given? ? yield(record) : perform(record) if _perform_callbacks.empty?
 
@@ -248,7 +288,7 @@ module RocketJob
         unless new_record?
           # Fail job iff no other worker has already finished it
           # Must set write concern to at least 1 since we need the nModified back
-          result   = self.class.with(write: {w: 1}) do |query|
+          result = self.class.with(write: {w: 1}) do |query|
             query.
               where(id: id, state: :running, sub_state: :processing).
               update({"$set" => {state: "failed", worker_name: worker_name}})

data/lib/rocket_job/config.rb

@@ -81,6 +81,11 @@ module RocketJob
       logger.debug "Reading Mongo configuration from: #{config_file}"
       ::Mongoid.load!(config_file, environment)
 
+      # Mongoid 9 requires `Time.zone` to be set in order to mongoize Date and
+      # Time values. When running outside of Rails it may be unset, so default
+      # it here without overriding an explicit application setting.
+      ::Time.zone_default ||= ::ActiveSupport::TimeZone["UTC"]
+
       config_file =
         if encryption_file_name
           Pathname.new(encryption_file_name)
@@ -100,7 +105,7 @@ module RocketJob
     def self.filter
       raise(ArgumentError, "Cannot supply both an include_filter and an exclude_filter") if include_filter && exclude_filter
 
-      filter                   = where_filter
+      filter = where_filter
       (filter ||= {})["_type"] = include_filter if include_filter
       (filter ||= {})["_type"] = {"$not" => exclude_filter} if exclude_filter
       filter&.dup

data/lib/rocket_job/dirmon_entry.rb

@@ -286,14 +286,16 @@ module RocketJob
       klass = job_class
       return unless klass
 
-      properties.each_pair do |k, _v|
-        next if klass.public_method_defined?("#{k}=".to_sym)
+      # Mongoid 9 returns Hash field keys as Strings, earlier versions as Symbols.
+      properties.each_pair do |raw_key, value|
+        k = raw_key.to_sym
+        next if klass.public_method_defined?(:"#{k}=")
 
         if %i[output_categories input_categories].include?(k)
           category_class = k == :input_categories ? RocketJob::Category::Input : RocketJob::Category::Output
-          properties[k].each do |category|
+          value.each do |category|
             category.each_pair do |key, _value|
-              next if category_class.public_method_defined?("#{key}=".to_sym)
+              next if category_class.public_method_defined?(:"#{key}=")
 
               errors.add(
                 :properties,

data/lib/rocket_job/event.rb

@@ -12,6 +12,11 @@ module RocketJob
 
     ALL_EVENTS = "*".freeze
 
+    # MongoDB OperationFailure codes that are safe to ignore when concurrently
+    # creating the polling collection and its TTL index:
+    #   48 NamespaceExists, 85 IndexOptionsConflict, 86 IndexKeySpecsConflict.
+    IGNORABLE_CREATE_CODES = [48, 85, 86].freeze
+
     # Capped collection long polling interval.
     class_attribute :long_poll_seconds, instance_accessor: false
     self.long_poll_seconds = 300
@@ -23,6 +28,28 @@ module RocketJob
     class_attribute :capped_collection_size, instance_accessor: false
     self.capped_collection_size = 128 * 1024 * 1024
 
+    # Event listener strategy:
+    #   :capped  - Tail a capped collection with a tailable cursor (default).
+    #              Lowest latency, but requires a data store that supports capped
+    #              collections and tailable cursors (i.e. a real MongoDB server).
+    #   :polling - Poll a regular collection for new events. Slightly higher latency
+    #              (bounded by `poll_interval`), but works on any MongoDB-compatible
+    #              store, including AWS DocumentDB which has no capped collections.
+    class_attribute :listener_strategy, instance_accessor: false
+    self.listener_strategy = :capped
+
+    # Polling strategy: seconds to wait between polls for new events.
+    class_attribute :poll_interval, instance_accessor: false
+    self.poll_interval = 1
+
+    # Polling strategy: seconds an event is retained before a TTL index removes it.
+    # Must comfortably exceed the longest expected listener downtime so that a
+    # restarting server can still recover events published while it was away.
+    #
+    # Default: 1 hour.
+    class_attribute :event_retention_seconds, instance_accessor: false
+    self.event_retention_seconds = 60 * 60
+
     # Mandatory Event Name
     #   Examples:
     #     '/rocket_job/config'
@@ -81,14 +108,23 @@ module RocketJob
       @subscribers.each_value { |v| v.delete_if { |i| i.object_id == handle } }
     end
 
-    # Indefinitely tail the capped collection looking for new events.
+    # Indefinitely watch for new events, dispatching each to its subscribers.
     #   time: the start time from which to start looking for new events.
     def self.listener(time: @load_time)
       Thread.current.name = "rocketjob event"
-      create_capped_collection
 
-      logger.info("Event listener started")
-      tail_capped_collection(time) { |event| process_event(event) }
+      case listener_strategy
+      when :capped
+        create_capped_collection
+        logger.info("Event listener started (capped collection)")
+        tail_capped_collection(time) { |event| process_event(event) }
+      when :polling
+        create_polling_collection
+        logger.info("Event listener started (polling, interval: #{poll_interval}s)")
+        poll_collection(time) { |event| process_event(event) }
+      else
+        raise(ArgumentError, "Unknown RocketJob::Event.listener_strategy: #{listener_strategy.inspect}")
+      end
     rescue Exception => e
       logger.error("#listener Event listener is terminating due to unhandled exception", e)
       raise(e)
@@ -134,6 +170,50 @@ module RocketJob
       retry
     end
 
+    # Create the regular (non-capped) collection used by the polling strategy,
+    # along with a TTL index that expires old events.
+    #
+    # Safe to call repeatedly: it never drops data, and tolerates the collection
+    # and index already existing.
+    def self.create_polling_collection
+      collection.client[collection_name].create unless collection_exists?
+      collection.indexes.create_one({created_at: 1}, expire_after: event_retention_seconds)
+    rescue Mongo::Error::OperationFailure => e
+      # Ignore "collection already exists" and "index already exists" races between
+      # multiple servers starting at once. Anything else is a real error.
+      raise(e) unless IGNORABLE_CREATE_CODES.include?(e.code)
+    end
+
+    # Indefinitely poll a regular collection for new events.
+    #   time: the start time from which to start looking for new events.
+    #
+    # After the first poll the `_id` of the last event seen is used as the
+    # watermark, which is monotonic and unique, so events sharing a `created_at`
+    # timestamp are never skipped.
+    def self.poll_collection(time, &block)
+      last_id = nil
+      loop do
+        last_id = poll_once(time, last_id, &block)
+        sleep(poll_interval)
+      end
+    rescue Mongo::Error::SocketError, Mongo::Error::SocketTimeoutError, Mongo::Error::OperationFailure, Timeout::Error => e
+      logger.info("Polling failed, retrying: #{e.class.name} #{e.message}")
+      sleep(poll_interval)
+      retry
+    end
+
+    # Perform a single polling pass, yielding every event newer than the watermark
+    # and returning the new watermark (the `_id` of the last event seen, or the
+    # supplied `last_id` when no new events were found).
+    def self.poll_once(time, last_id = nil)
+      filter = last_id ? {_id: {"$gt" => last_id}} : {created_at: {"$gt" => time}}
+      collection.find(filter).sort(_id: 1).each do |doc|
+        last_id = doc["_id"]
+        yield(Mongoid::Factory.from_db(Event, doc))
+      end
+      last_id
+    end
+
     # Process a new event, calling registered subscribers.
     def self.process_event(event)
       logger.info("Event Received", event.attributes)

data/lib/rocket_job/extensions/mongo/logging.rb

@@ -4,6 +4,7 @@ module Mongo
   class Monitoring
     class CommandLogSubscriber
       include SemanticLogger::Loggable
+
       logger.name = "Mongo"
 
       undef :started

data/lib/rocket_job/extensions/mongoid/clients/options.rb

@@ -11,7 +11,7 @@ module RocketJob
       end
 
       def collection(parent = nil)
-        @collection_name ? mongo_client[@collection_name] : super(parent)
+        @collection_name ? mongo_client[@collection_name] : super
       end
 
       def collection_name
@@ -31,5 +31,5 @@ module RocketJob
   end
 end
 
-::Mongoid::Criteria.include(RocketJob::MongoidClients::Options)
-::Mongoid::Document.include(RocketJob::MongoidClients::Options)
+Mongoid::Criteria.include(RocketJob::MongoidClients::Options)
+Mongoid::Document.include(RocketJob::MongoidClients::Options)

data/lib/rocket_job/extensions/mongoid/contextual/mongo.rb

@@ -1,15 +1,14 @@
-::Mongoid::Contextual::Mongo
 module Mongoid
   module Contextual
     class Mongo
       def initialize(criteria)
         @criteria = criteria
         @klass    = criteria.klass
-        @cache    = criteria.options[:cache]
-        # Only line changed is here, get collection name from criteria, not @klass
+        # Only line changed from the Mongoid implementation is here: fetch the
+        # collection from the criteria so a custom collection_name is honored
+        # rather than always using @klass.collection.
         # @collection = @klass.collection
         @collection = criteria.collection
-
         criteria.send(:merge_type_selection)
         @view = collection.find(criteria.selector, session: _session)
         apply_options

data/lib/rocket_job/extensions/mongoid/factory.rb

@@ -4,11 +4,11 @@ module RocketJob
   # Don't convert to Mongoid::Factory since it conflicts with Mongoid use.
   module MongoidFactory
     def from_db(klass, attributes = nil, criteria = nil, selected_fields = nil)
-      obj                 = super(klass, attributes, criteria, selected_fields)
+      obj                 = super
       obj.collection_name = criteria.collection_name if criteria
       obj
     end
   end
 end
 
-::Mongoid::Factory.extend(RocketJob::MongoidFactory)
+Mongoid::Factory.extend(RocketJob::MongoidFactory)

data/lib/rocket_job/extensions/psych/yaml_tree.rb

@@ -1,8 +1,12 @@
 require "psych/visitors/yaml_tree"
 
-class Psych::Visitors::YAMLTree
-  # Serialize IOStream path as a string
-  def visit_IOStreams_Path(o)
-    visit_String(o.to_s)
+module Psych
+  module Visitors
+    class YAMLTree
+      # Serialize IOStream path as a string
+      def visit_IOStreams_Path(o)
+        visit_String(o.to_s)
+      end
+    end
   end
 end

data/lib/rocket_job/extensions/rocket_job_adapter.rb

@@ -4,7 +4,7 @@ module ActiveJob
     #
     # Ruby's missing batch system.
     #
-    # Read more about Rocket Job {here}[http://rocketjob.io].
+    # Read more about Rocket Job {here}[https://rocketjob.reidmorrison.com].
     #
     # To use Rocket Job set the queue_adapter config to +:rocket_job+.
     #

data/lib/rocket_job/jobs/active_job.rb

@@ -1,7 +1,7 @@
 module RocketJob
   module Jobs
     # Used to wrap an Active Job
-    class ActiveJob < RocketJob::Job #:nodoc:
+    class ActiveJob < RocketJob::Job # :nodoc:
       field :data, type: Hash
       field :active_job_id, type: String
       field :active_job_class, type: String

data/lib/rocket_job/jobs/dirmon_job.rb

@@ -85,7 +85,9 @@ module RocketJob
           file_names[key] = size if size
         end
       rescue StandardError => e
-        logger.error("Dirmon Entry: #{dirmon_entry.id} failed. Moved to `failed` state to prevent processing again without manual intervention.", e)
+        logger.error(
+          "Dirmon Entry: #{dirmon_entry.id} failed. Moved to `failed` state to prevent processing again without manual intervention.", e
+        )
         dirmon_entry.fail(worker_name, e)
         dirmon_entry.save(validate: false)
       end

data/lib/rocket_job/jobs/on_demand_batch_job.rb

@@ -105,7 +105,7 @@ module RocketJob
 
       # Add a new output category and collect output for it.
       def add_output_category(**args)
-        self.output_categories << RocketJob::Category::Output.new(**args)
+        output_categories << RocketJob::Category::Output.new(**args)
       end
 
       private

data/lib/rocket_job/jobs/upload_file_job.rb

@@ -94,11 +94,12 @@ module RocketJob
       end
 
       VALID_INSTANCE_METHODS = %i[upload upload_file_name= full_file_name=].freeze
+      private_constant :VALID_INSTANCE_METHODS
 
       # Validates job_class is a Rocket Job
       def job_implements_upload
         klass = job_class
-        return if klass.nil? || klass.instance_methods.any? { |m| VALID_INSTANCE_METHODS.include?(m) }
+        return if klass.nil? || klass.instance_methods.intersect?(VALID_INSTANCE_METHODS)
 
         errors.add(:job_class_name,
                    "#{job_class} must implement any one of: :#{VALID_INSTANCE_METHODS.join(' :')} instance methods")
@@ -120,14 +121,16 @@ module RocketJob
         klass = job_class
         return unless klass
 
-        properties.each_pair do |k, _v|
-          next if klass.public_method_defined?("#{k}=".to_sym)
+        # Mongoid 9 returns Hash field keys as Strings, earlier versions as Symbols.
+        properties.each_pair do |raw_key, value|
+          k = raw_key.to_sym
+          next if klass.public_method_defined?(:"#{k}=")
 
           if %i[output_categories input_categories].include?(k)
             category_class = k == :input_categories ? RocketJob::Category::Input : RocketJob::Category::Output
-            properties[k].each do |category|
+            value.each do |category|
               category.each_pair do |key, _value|
-                next if category_class.public_method_defined?("#{key}=".to_sym)
+                next if category_class.public_method_defined?(:"#{key}=")
 
                 errors.add(
                   :properties,

data/lib/rocket_job/lookup_collection.rb

@@ -12,8 +12,8 @@ module RocketJob
     #   end
     #
     #   input_category(:my_lookup).find(id: 123).first
-    def upload(batch_size: 10_000, &block)
-      BatchUploader.upload(batch_size: batch_size, &block)
+    def upload(batch_size: 10_000, &)
+      BatchUploader.upload(batch_size: batch_size, &)
     end
 
     # Looks up the value at the specified id.

data/lib/rocket_job/performance.rb

@@ -18,7 +18,7 @@ module RocketJob
     # Loads the queue with jobs to be processed once the queue is loaded.
     # Retain the first and last job for timings, all others are destroyed on completion.
     def run_test_case(count = self.count)
-      if RocketJob::Server.where(:state.in => %w[running paused]).count.zero?
+      if RocketJob::Server.where(:state.in => %w[running paused]).none?
         raise "Please start servers before starting the performance test"
       end
 

data/lib/rocket_job/plugins/cron.rb

@@ -18,7 +18,8 @@ module RocketJob
 
         # Whether to prevent another instance of this job from running with the exact _same_ cron schedule.
         # Another job instance with a different `cron_schedule` string is permitted.
-        field :cron_singleton, type: Mongoid::Boolean, default: true, class_attribute: true, user_editable: true, copy_on_restart: true
+        field :cron_singleton, type: Mongoid::Boolean, default: true, class_attribute: true, user_editable: true,
+copy_on_restart: true
 
         # Whether to re-schedule the next job occurrence when this job starts, or when it is complete.
         #
@@ -38,7 +39,8 @@ module RocketJob
         #     at any time until after the job has failed, or is aborted.
         #   - To prevent this job creating any new duplicate instances during subsequent processing,
         #     its `cron_schedule` is set to `nil` after it fails or is aborted.
-        field :cron_after_start, type: Mongoid::Boolean, default: true, class_attribute: true, user_editable: true, copy_on_restart: true
+        field :cron_after_start, type: Mongoid::Boolean, default: true, class_attribute: true, user_editable: true,
+copy_on_restart: true
 
         validates_each :cron_schedule do |record, attr, value|
           record.errors.add(attr, "Invalid cron_schedule: #{value.inspect}") if value && !Fugit::Cron.new(value)
@@ -88,7 +90,8 @@ module RocketJob
       def rocket_job_cron_singleton_check
         return if cron_schedule.nil? || completed? || aborted? || !rocket_job_cron_duplicate?
 
-        errors.add(:state, "Another instance of #{self.class.name} is already queued, running, failed, or paused with the same cron schedule: #{cron_schedule}")
+        errors.add(:state,
+                   "Another instance of #{self.class.name} is already queued, running, failed, or paused with the same cron schedule: #{cron_schedule}")
       end
     end
   end

data/lib/rocket_job/plugins/document.rb

@@ -11,7 +11,6 @@ module RocketJob
         store_in client: "rocketjob"
       end
 
-      # rubocop:disable Style/RedundantSort
       module ClassMethods
         # Mongoid does not apply ordering, add sort
         def first
@@ -23,7 +22,6 @@ module RocketJob
           all.sort("_id" => -1).first
         end
       end
-      # rubocop:enable Style/RedundantSort
 
       private
 

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

@@ -17,7 +17,7 @@ module RocketJob
         #   - log_exception logs entire exception if raised
         #   - on_exception_level changes log level from info to error on exception
         #   - silence noisy jobs by raising log level
-        def rocket_job_around_logger(&block)
+        def rocket_job_around_logger(&)
           logger.info("Start #perform")
           logger.measure_info(
             "Completed #perform",
@@ -25,7 +25,7 @@ module RocketJob
             log_exception:      :full,
             on_exception_level: :error,
             silence:            log_level,
-            &block
+            &
           )
         end
       end

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

@@ -185,7 +185,7 @@ module RocketJob
               self.rocket_job_restart_attributes += [name.to_sym]
             end
 
-            super(name, options)
+            super
           end
 
           # Builds this job instance from the supplied properties hash.

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

@@ -79,8 +79,8 @@ module RocketJob
             return
           end
 
-          job_attrs = self.class.rocket_job_restart_attributes.each_with_object({}) do |attr, attrs|
-            attrs[attr] = send(attr)
+          job_attrs = self.class.rocket_job_restart_attributes.to_h do |attr|
+            [attr, send(attr)]
           end
           job_attrs.merge!(overrides)
 

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

@@ -30,6 +30,13 @@ module RocketJob
 
         included do
           class_attribute :rocket_job_throttles
+
+          # Human readable reason why this job is currently being throttled.
+          # Set when a throttle prevents the job from running, cleared when it starts.
+          # Surfaced in Rocket Job Mission Control.
+          field :throttled_by, type: String
+          # Time at which this job was last throttled.
+          field :throttled_at, type: Time
         end
 
         module ClassMethods
@@ -45,11 +52,16 @@ module RocketJob
           #     Or, a block that will return the filter.
           #     Default: :throttle_filter_class (Throttle all jobs of this class)
           #
+          #   description: [String|Proc]
+          #     Human readable reason why the job is throttled, persisted to `throttled_by`
+          #     and shown in Mission Control. A Proc is called with the job and must
+          #     return a String. Default: a humanized version of the method name.
+          #
           # Note: Throttles are executed in the order they are defined.
-          def define_throttle(method_name, filter: :throttle_filter_class)
+          def define_throttle(method_name, filter: :throttle_filter_class, description: nil)
             # Duplicate to prevent modifying parent class throttles
             definitions = rocket_job_throttles ? rocket_job_throttles.deep_dup : ThrottleDefinitions.new
-            definitions.add(method_name, filter)
+            definitions.add(method_name, filter, description)
             self.rocket_job_throttles = definitions
           end
 

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

@@ -32,7 +32,10 @@ module RocketJob
           # Allow jobs to be throttled by group name instance of the job class name.
           field :throttle_group, type: String, class_attribute: true, user_editable: true, copy_on_restart: true
 
-          define_throttle :throttle_running_jobs_exceeded?
+          define_throttle :throttle_running_jobs_exceeded?,
+                          description: lambda { |job, *|
+                            "Throttled: maximum of #{job.throttle_running_jobs} running jobs reached"
+                          }
         end
 
         private

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

@@ -66,10 +66,13 @@ module RocketJob
         # re_raise_exceptions: [true|false]
         #   Re-raise the exception after updating the job
         #   Default: false
-        def fail_on_exception!(re_raise_exceptions = false, &block)
-          SemanticLogger.named_tagged(job: id.to_s, &block)
+        def fail_on_exception!(re_raise_exceptions = false, &)
+          SemanticLogger.named_tagged(job: id.to_s, &)
         rescue Exception => e
           SemanticLogger.named_tagged(job: id.to_s) do
+            # Not a guard clause: the `fail` event clears `worker_name`, so the
+            # branches are not equivalent and must not be collapsed.
+            # rubocop:disable-next Style/GuardClause
             if failed? || !may_fail?
               self.exception        = JobException.from_exception(e)
               exception.worker_name = worker_name

data/lib/rocket_job/plugins/retry.rb

@@ -126,7 +126,7 @@ module RocketJob
       # Or, to see the total durations based on the number of retries:
       #   (0..count).map{|i| "#{i+1} ==> #{RocketJob.seconds_as_duration(intervals[0..i].sum)}"}
       def rocket_job_retry_seconds_to_delay
-        rocket_job_failure_count**4 + 5
+        (rocket_job_failure_count**4) + 5
       end
     end
   end