rocketjob 6.3.2 → 7.0.0

data/lib/rocket_job/plugins/throttle_dependent_jobs.rb

@@ -13,8 +13,13 @@ module RocketJob
       included do
         field :dependent_jobs, type: Array, class_attribute: true, user_editable: true, copy_on_restart: true
 
-        define_throttle :dependent_jobs_running?
-        define_batch_throttle :dependent_jobs_running? if respond_to?(:define_batch_throttle)
+        dependent_jobs_description = lambda { |job, *|
+          "Throttled: dependent jobs are running (#{Array(job.dependent_jobs).join(', ')})"
+        }
+        define_throttle :dependent_jobs_running?, description: dependent_jobs_description
+        if respond_to?(:define_batch_throttle)
+          define_batch_throttle :dependent_jobs_running?, description: dependent_jobs_description
+        end
       end
 
       class_methods do

data/lib/rocket_job/plugins/transaction.rb

@@ -41,8 +41,8 @@ module RocketJob
 
       private
 
-      def rocket_job_transaction(&block)
-        ActiveRecord::Base.transaction(&block)
+      def rocket_job_transaction(&)
+        ActiveRecord::Base.transaction(&)
       end
     end
   end

data/lib/rocket_job/sliced/input.rb

@@ -1,10 +1,10 @@
 module RocketJob
   module Sliced
     class Input < Slices
-      def upload(**args, &block)
+      def upload(**args, &)
         # Create indexes before uploading
         create_indexes
-        Writer::Input.collect(self, **args, &block)
+        Writer::Input.collect(self, **args, &)
       rescue Exception => e
         drop
         raise(e)
@@ -117,19 +117,24 @@ module RocketJob
         )
       end
 
-      # Returns the next slice to work on in id order
-      # Returns nil if there are currently no queued slices
+      # Claims and returns the next queued slice for this worker.
+      # Returns nil if there are currently no queued slices.
       #
-      # If a slice is in queued state it will be started and assigned to this worker
+      # No explicit sort is applied. Forcing the global minimum `_id` (a
+      # `sort("_id" => 1)`) makes every worker target the same document, so under
+      # concurrency they collide on the atomic claim: one wins and the rest hit a
+      # WriteConflict ("Document no longer matches the predicate") and retry,
+      # which throttles a large batch job as workers are added. Without the sort,
+      # the `{state: 1, _id: 1}` index still yields queued slices in roughly `_id`
+      # (upload) order, but concurrent workers land on different documents instead
+      # of contending for one. Output ordering is unaffected: each output slice
+      # inherits its input slice's `_id` and downloads read in `_id` order.
       def next_slice(worker_name)
-        # TODO: Will it perform faster without the id sort?
-        # I.e. Just process on a FIFO basis?
         document                 = all.queued.
-          sort("_id" => 1).
-          find_one_and_update(
-            {"$set" => {worker_name: worker_name, state: "running", started_at: Time.now}},
-            return_document: :after
-          )
+                                   find_one_and_update(
+                                     {"$set" => {worker_name: worker_name, state: "running", started_at: Time.now}},
+                                     return_document: :after
+                                   )
         document.collection_name = collection_name if document
         document
       end

data/lib/rocket_job/sliced/slice.rb

@@ -154,8 +154,8 @@ module RocketJob
       end
 
       # Fail this slice if an exception occurs during processing.
-      def fail_on_exception!(re_raise_exceptions = false, &block)
-        SemanticLogger.named_tagged(slice: id.to_s, &block)
+      def fail_on_exception!(re_raise_exceptions = false, &)
+        SemanticLogger.named_tagged(slice: id.to_s, &)
       rescue Exception => e
         SemanticLogger.named_tagged(slice: id.to_s) do
           if failed? || !may_fail?
@@ -175,7 +175,7 @@ module RocketJob
 
       # Always add records to any updates.
       def atomic_updates(*args)
-        r                             = super(*args)
+        r = super
         (r["$set"] ||= {})["records"] = serialize_records if @records
         r
       end

data/lib/rocket_job/sliced/slices.rb

@@ -44,8 +44,8 @@ module RocketJob
 
       # Returns output slices in the order of their id
       # which is usually the order in which they were written.
-      def each(&block)
-        all.sort(id: 1).each(&block)
+      def each(&)
+        all.sort(id: 1).each(&)
       end
 
       # Insert a new slice into the collection
@@ -120,7 +120,7 @@ module RocketJob
       end
 
       # Forward additional methods.
-      def_instance_delegators :@all, :collection, :count, :delete_all, :first, :find, :last, :nor, :not, :or, :to_a, :where
+      def_instance_delegators :@all, :collection, :count, :delete_all, :find, :nor, :not, :or, :to_a, :where
 
       # Drop this collection when it is no longer needed
       def drop
@@ -145,7 +145,6 @@ module RocketJob
       end
 
       # Mongoid does not apply ordering, add sort
-      # rubocop:disable Style/RedundantSort
       def first
         all.sort("_id" => 1).first
       end
@@ -154,8 +153,6 @@ module RocketJob
         all.sort("_id" => -1).first
       end
 
-      # rubocop:enable Style/RedundantSort
-
       # Returns [Array<Struct>] grouped exceptions by class name,
       # and unique exception messages by exception class.
       #

data/lib/rocket_job/supervisor.rb

@@ -92,8 +92,8 @@ module RocketJob
       end
     end
 
-    def synchronize(&block)
-      @mutex.synchronize(&block)
+    def synchronize(&)
+      @mutex.synchronize(&)
     end
   end
 end

data/lib/rocket_job/thread_worker.rb

@@ -8,7 +8,7 @@ module RocketJob
     attr_reader :thread
 
     def initialize(id:, server_name:)
-      super(id: id, server_name: server_name)
+      super
       @shutdown = Concurrent::Event.new
       @thread   = Thread.new { run }
     end
@@ -21,8 +21,8 @@ module RocketJob
       @thread.backtrace
     end
 
-    def join(*args)
-      @thread.join(*args)
+    def join(*)
+      @thread.join(*)
     end
 
     # Send each active worker the RocketJob::ShutdownException so that stops processing immediately.

data/lib/rocket_job/throttle_definition.rb

@@ -1,10 +1,18 @@
 module RocketJob
   class ThrottleDefinition
-    attr_reader :method_name, :filter
+    attr_reader :method_name, :filter, :description
 
-    def initialize(method_name, filter)
+    # Parameters:
+    #   description: [String|Proc|nil]
+    #     Human readable reason why the job is throttled, persisted to the job as
+    #     `throttled_by` and surfaced in Mission Control.
+    #     When a Proc, it is called with the same arguments as the throttle and must
+    #     return a String, allowing the reason to include runtime detail.
+    #     When nil, a humanized version of the method name is used.
+    def initialize(method_name, filter, description = nil)
       @method_name = method_name.to_sym
       @filter      = filter
+      @description = description
     end
 
     # Returns [true|false] whether the throttle was triggered.
@@ -33,5 +41,14 @@ module RocketJob
         job.send(filter)
       end
     end
+
+    # Returns [String] the human readable reason why the job is throttled.
+    def extract_description(job, *)
+      return description.call(job, *) if description.is_a?(Proc)
+      return description if description
+
+      # Default: humanize the method name, dropping a trailing `?` or `_exceeded`.
+      method_name.to_s.sub(/_exceeded\?\z/, "").sub(/\?\z/, "").tr("_", " ").capitalize
+    end
   end
 end

data/lib/rocket_job/throttle_definitions.rb

@@ -6,13 +6,13 @@ module RocketJob
       @throttles = []
     end
 
-    def add(method_name, filter)
+    def add(method_name, filter, description = nil)
       unless filter.is_a?(Symbol) || filter.is_a?(Proc)
         raise(ArgumentError, "Filter for #{method_name} must be a Symbol or Proc")
       end
       raise(ArgumentError, "Cannot define #{method_name} twice, undefine previous throttle first") if exist?(method_name)
 
-      @throttles += [ThrottleDefinition.new(method_name, filter)]
+      @throttles += [ThrottleDefinition.new(method_name, filter, description)]
     end
 
     # Undefine a previously defined throttle
@@ -25,15 +25,20 @@ module RocketJob
       throttles.any? { |throttle| throttle.method_name == method_name }
     end
 
-    # Returns the matching filter,
+    # Returns [ThrottleDefinition] the first throttle that was triggered,
     # or nil if no throttles were triggered.
-    def matching_filter(job, *args)
-      throttles.each do |throttle|
-        next unless throttle.throttled?(job, *args)
+    #
+    # The returned definition exposes both the filter (`extract_filter`) and the
+    # human readable reason (`extract_description`) so callers can apply the filter
+    # and persist why the job was throttled.
+    def matching_throttle(job, *args)
+      throttles.find { |throttle| throttle.throttled?(job, *args) }
+    end
 
-        return throttle.extract_filter(job, *args)
-      end
-      nil
+    # Returns the matching filter,
+    # or nil if no throttles were triggered.
+    def matching_filter(job, *)
+      matching_throttle(job, *)&.extract_filter(job, *)
     end
 
     def deep_dup

data/lib/rocket_job/version.rb

@@ -1,3 +1,3 @@
 module RocketJob
-  VERSION = "6.3.2".freeze
+  VERSION = "7.0.0".freeze
 end

data/lib/rocket_job/worker.rb

@@ -63,25 +63,29 @@ module RocketJob
       logger.info "Started"
 
       until shutdown?
-        sleep_seconds = Config.max_poll_seconds
         reset_filter_if_expired
         job = next_available_job
 
-        # Returns true when work was completed, but no other work is available
-        if job&.rocket_job_work(self, false)
-          # Return the database connections for this fiber back to the connection pool
-          if defined?(ActiveRecord::Base)
-            if ActiveRecord::Base.respond_to?(:connection_handler)
-              # Rails 7 .2
-              ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+        if job
+          # Returns true when this job has no more work immediately available,
+          # for example a batch job that has run out of slices, or was throttled.
+          no_immediate_work = job.rocket_job_work(self, false)
+
+          # Return the database connections for this thread back to the connection pool.
+          release_active_record_connections
+
+          sleep_seconds =
+            if no_immediate_work
+              # Stagger workers so that they don't all poll at the same time.
+              random_wait_interval
             else
-              ActiveRecord::Base.clear_active_connections!
+              # Work was performed and more queued work is likely available,
+              # so poll again immediately rather than waiting a full interval.
+              0
             end
-          end
-          
-
-          # Stagger workers so that they don't all poll at the same time.
-          sleep_seconds = random_wait_interval
+        else
+          # No work was found, so wait the full poll interval before checking again.
+          sleep_seconds = Config.max_poll_seconds
         end
 
         wait_for_shutdown?(sleep_seconds)
@@ -91,12 +95,18 @@ module RocketJob
     rescue Exception => e
       logger.fatal("Unhandled exception in job processing thread", e)
     ensure
-      if defined?(ActiveRecord::Base)
-        if ActiveRecord::Base.respond_to?(:connection_handler)
-          ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
-        else
-          ActiveRecord::Base.clear_active_connections!
-        end
+      release_active_record_connections
+    end
+
+    # Return the database connections for this thread back to the connection pool.
+    def release_active_record_connections
+      return unless defined?(ActiveRecord::Base)
+
+      if ActiveRecord::Base.respond_to?(:connection_handler)
+        # Rails 7.2+
+        ActiveRecord::Base.connection_handler.clear_active_connections!(:all)
+      else
+        ActiveRecord::Base.clear_active_connections!
       end
     end
 
@@ -149,12 +159,19 @@ module RocketJob
     # Whether the supplied job has been throttled and should be ignored.
     def throttled_job?(job)
       # Evaluate job throttles, if any.
-      filter = job.rocket_job_throttles.matching_filter(job)
-      return false unless filter
-
-      add_to_current_filter(filter)
-      # Restore retrieved job so that other workers can process it later
-      job.set(worker_name: nil, state: :queued)
+      throttle = job.rocket_job_throttles.matching_throttle(job)
+      return false unless throttle
+
+      add_to_current_filter(throttle.extract_filter(job))
+      # Restore retrieved job so that other workers can process it later, recording
+      # why it was throttled so it is visible in Mission Control. This reuses the
+      # write that requeues the job, so it adds no extra database round trip.
+      job.set(
+        worker_name:  nil,
+        state:        :queued,
+        throttled_by: throttle.extract_description(job),
+        throttled_at: Time.now
+      )
       true
     end
 
@@ -164,14 +181,46 @@ module RocketJob
     # Applies the current filter to exclude filtered jobs.
     #
     # Returns nil if no jobs are available for processing.
+    #
+    # Notes:
+    # - An already running batch job is _joined_ with a read-only query, since
+    #   concurrency for a batch job is coordinated per-slice (see
+    #   `Sliced::Input#next_slice`), not on the job document. Writing
+    #   `worker_name`/`state` to the shared job document on every poll turns it
+    #   into a write-contention hotspot: with many workers MongoDB serializes the
+    #   updates and retries the write conflicts (server log id 46404), which is
+    #   what makes a large batch job slow down as workers are added.
+    # - Only a queued job is claimed with a write, transitioning it to running.
+    #   That write is naturally distributed: each queued job is claimed once.
     def find_and_assign_job
       SemanticLogger.silence(:info) do
         scheduled = RocketJob::Job.where(run_at: nil).or(:run_at.lte => Time.now)
         working   = RocketJob::Job.queued.or(state: "running", sub_state: "processing")
         query     = RocketJob::Job.and(working, scheduled)
         query     = query.and(current_filter) unless current_filter.blank?
-        update    = {"$set" => {"worker_name" => name, "state" => "running"}}
-        query.sort(priority: 1, _id: 1).find_one_and_update(update, bypass_document_validation: true)
+        query     = query.sort(priority: 1, _id: 1)
+
+        # Retry only when a queued job was claimed by another worker first.
+        loop do
+          job = query.first
+          return nil unless job
+
+          # Already running batch job: join it without writing to the job document.
+          return job if job.running?
+
+          # Queued job: claim it atomically, guarding on it still being queued.
+          # find_one_and_update returns the pre-image (state: queued) so that the
+          # caller still runs throttles and `start!`.
+          # Clear any stale throttle reason from a previous throttled poll so a job
+          # that is now allowed to run no longer reports as throttled in Mission Control.
+          update = {
+            "$set"   => {"worker_name" => name, "state" => "running"},
+            "$unset" => {"throttled_by" => "", "throttled_at" => ""}
+          }
+          claimed = RocketJob::Job.queued.where(id: job.id).
+                    find_one_and_update(update, bypass_document_validation: true)
+          return claimed if claimed
+        end
       end
     end
 

data/lib/rocketjob.rb

@@ -31,7 +31,6 @@ module RocketJob
   autoload :LookupCollection,        "rocket_job/lookup_collection"
   autoload :Worker,                  "rocket_job/worker"
   autoload :Performance,             "rocket_job/performance"
-  autoload :RactorWorker,            "rocket_job/ractor_worker"
   autoload :Server,                  "rocket_job/server"
   autoload :Sliced,                  "rocket_job/sliced"
   autoload :Subscriber,              "rocket_job/subscriber"
@@ -83,7 +82,7 @@ module RocketJob
     autoload :UploadFileJob,         "rocket_job/jobs/upload_file_job"
 
     module ReEncrypt
-      autoload :RelationalJob,       "rocket_job/jobs/re_encrypt/relational_job"
+      autoload :RelationalJob, "rocket_job/jobs/re_encrypt/relational_job"
     end
   end
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rocketjob
 version: !ruby/object:Gem::Version
-  version: 6.3.2
+  version: 7.0.0
 platform: ruby
 authors:
 - Reid Morrison
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aasm
@@ -56,62 +55,65 @@ dependencies:
   name: iostreams
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: mongoid
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.5'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.5'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: semantic_logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.7'
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.7'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: symmetric-encryption
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.3'
+        version: '4.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.3'
-description:
-email:
+        version: '4.6'
+description: Rocket Job is a distributed, priority-based, MongoDB-backed batch processing
+  system for Ruby. Run conventional background jobs, or split a single job's input
+  into slices and process it concurrently across thousands of workers, spilling from
+  memory to disk so very large files never fall over.
 executables:
 - rocketjob
+- rocketjob_batch_perf
 - rocketjob_perf
 extensions: []
 extra_rdoc_files: []
@@ -186,7 +188,6 @@ files:
 - lib/rocket_job/plugins/state_machine.rb
 - lib/rocket_job/plugins/throttle_dependent_jobs.rb
 - lib/rocket_job/plugins/transaction.rb
-- lib/rocket_job/ractor_worker.rb
 - lib/rocket_job/railtie.rb
 - lib/rocket_job/rocket_job.rb
 - lib/rocket_job/server.rb
@@ -217,11 +218,16 @@ files:
 - lib/rocket_job/worker.rb
 - lib/rocket_job/worker_pool.rb
 - lib/rocketjob.rb
-homepage: https://rocketjob.io
+homepage: https://rocketjob.reidmorrison.com
 licenses:
 - Apache-2.0
-metadata: {}
-post_install_message:
+metadata:
+  bug_tracker_uri: https://github.com/reidmorrison/rocketjob/issues
+  changelog_uri: https://github.com/reidmorrison/rocketjob/blob/main/CHANGELOG.md
+  documentation_uri: https://rocketjob.reidmorrison.com
+  homepage_uri: https://rocketjob.reidmorrison.com
+  source_code_uri: https://github.com/reidmorrison/rocketjob/tree/v7.0.0
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -229,15 +235,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Ruby's missing batch processing system.
+summary: Process millions of records across thousands of workers. A distributed, MongoDB-backed
+  batch processing system for Ruby.
 test_files: []

data/lib/rocket_job/ractor_worker.rb

@@ -1,42 +0,0 @@
-module RocketJob
-  # Run each worker in its own "Ractor".
-  class RactorWorker < Worker
-    attr_reader :thread
-
-    def initialize(id:, server_name:)
-      super(id: id, server_name: server_name)
-      @shutdown = Concurrent::Event.new
-      @thread   = Ractor.new(name: "rocketjob-#{id}") { run }
-    end
-
-    def alive?
-      @thread.alive?
-    end
-
-    def backtrace
-      @thread.backtrace
-    end
-
-    def join(*args)
-      @thread.join(*args)
-    end
-
-    # Send each active worker the RocketJob::ShutdownException so that stops processing immediately.
-    def kill
-      @thread.raise(Shutdown, "Shutdown due to kill request for worker: #{name}") if @thread.alive?
-    end
-
-    def shutdown?
-      @shutdown.set?
-    end
-
-    def shutdown!
-      @shutdown.set
-    end
-
-    # Returns [true|false] whether the shutdown indicator was set
-    def wait_for_shutdown?(timeout = nil)
-      @shutdown.wait(timeout)
-    end
-  end
-end