workhorse 1.4.5 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef9cd623d06cab42a5c5a849f9a5c334c0bb8f4dd517f2c84e5ba3c4df611b24
-  data.tar.gz: 9681900417bc660a347afeeaebf6cf57fa342268afc38c24b4e5ce11479ce1e3
+  metadata.gz: 5b370f18088a986d133800af502b072749a8ae3b1b56585abc7cd6e086a40f7f
+  data.tar.gz: 7554e03f2927f9915013993d0da0401772bf201a993ae56b54e3631d295faa0b
 SHA512:
-  metadata.gz: 86a5b9f9db82efbd890dc77fa763dcc1052027df45d922358428e721bfe3e900670e28b1e55af06e04972fef7c6408fe8a445239443f0707063281d4baf344fe
-  data.tar.gz: 74f47b979b3589b5530947638c7ec7a6acbb9f85599c88bd9eccaf25fcecf5a92addecb58fa9357bc07eb840bf16b31e5a7fe7fe2f9a6e11fa697b31d9aaf526
+  metadata.gz: d75f21bb4784267b96dd047cf04f652458265b335a9020f3ae101d5aa85e18078ef37ed16d67c3bb2b6a4f47f696f4b9286817b3138b902644ef7ee799614140
+  data.tar.gz: 67aaa64b06d6523e3d4bfa90dfa1053134e79f877208e0077e3adaa6b61fb8a5c6ae10c0c61e6d1f4254131e0106e9cc3ca32546db3bbafd41d6dbff7af938a6

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Workhorse Changelog
 
+## 1.5.1 - 2026-07-22
+
+* Add per-worker heartbeat files. On every successful poll, each worker touches
+  `tmp/pids/workhorse.<daemon_id>.heartbeat` (keyed by daemon worker id, the same
+  id used for the pidfile). The file's mtime provides a stable per-worker
+  "last polled at" clock that survives restarts, letting external monitoring
+  detect dead, crash-looping, or hung workers. The daemon exposes the worker id
+  to the forked worker process via the `WORKHORSE_DAEMON_WORKER_ID` environment
+  variable.
+
+  Sitrox reference: #151020.
+
+## 1.5.0 - 2026-07-01
+
+* Change `DetectStaleJobsJob` to accept `locked_to_started_threshold` and
+  `run_time_threshold` as keyword arguments instead of reading from global
+  configuration. The config options `Workhorse.stale_detection_locked_to_started_threshold`
+  and `Workhorse.stale_detection_run_time_threshold` have been removed.
+
+  If you were previously configuring thresholds globally:
+
+  ```ruby
+  # Before
+  Workhorse.setup do |config|
+    config.stale_detection_locked_to_started_threshold = 300
+    config.stale_detection_run_time_threshold = 3600
+  end
+  Workhorse.enqueue(DetectStaleJobsJob.new)
+
+  # After
+  Workhorse.enqueue(DetectStaleJobsJob.new(locked_to_started_threshold: 300, run_time_threshold: 3600))
+  ```
+
+* Add `queues` keyword argument to `DetectStaleJobsJob` to restrict stale job
+  detection to specific queues. When omitted, all queues are checked (existing
+  behavior).
+
+  Sitrox reference: #132256.
+
 ## 1.4.5 - 2026-05-09
 
 * Close the lockfile after releasing the lock in the ShellHandler.

data/VERSION

@@ -1 +1 @@
-1.4.5
+1.5.1

data/lib/workhorse/daemon.rb

@@ -314,6 +314,10 @@ module Workhorse
         $stdout.reopen null_out
         $stderr.reopen null_out
 
+        # Expose the daemon worker id so the worker can key its heartbeat file
+        # by slot (see Workhorse::Worker#heartbeat!). Same id as the pidfile.
+        ENV['WORKHORSE_DAEMON_WORKER_ID'] = worker.id.to_s
+
         worker.block.call
       end
       worker.pid = pid

data/lib/workhorse/jobs/detect_stale_jobs_job.rb

@@ -5,24 +5,27 @@ module Workhorse::Jobs
   # exception is thrown (which may cause a notification if you configured
   # {Workhorse.on_exception} accordingly).
   #
-  # The thresholds are obtained from the configuration options
-  # {Workhorse.stale_detection_locked_to_started_threshold} and
-  # {Workhorse.stale_detection_run_time_threshold}.
-  #
-  # @example Schedule stale job detection
+  # @example Schedule stale job detection with default thresholds
   #   Workhorse.enqueue(DetectStaleJobsJob.new)
   #
-  # @example Configure thresholds
-  #   Workhorse.setup do |config|
-  #     config.stale_detection_locked_to_started_threshold = 300  # 5 minutes
-  #     config.stale_detection_run_time_threshold = 3600         # 1 hour
-  #   end
+  # @example Schedule with custom thresholds
+  #   Workhorse.enqueue(DetectStaleJobsJob.new(locked_to_started_threshold: 300, run_time_threshold: 3600))
+  #
+  # @example Only check specific queues
+  #   Workhorse.enqueue(DetectStaleJobsJob.new(queues: ['mailer', 'reports']))
   class DetectStaleJobsJob
     # Creates a new stale job detection job.
-    # Reads configuration thresholds at initialization time.
-    def initialize
-      @locked_to_started_threshold = Workhorse.stale_detection_locked_to_started_threshold
-      @run_time_threshold          = Workhorse.stale_detection_run_time_threshold
+    #
+    # @param locked_to_started_threshold [Integer] Maximum number of seconds a job is
+    #   allowed to stay 'locked' before an exception is raised. Set to 0 to skip this check.
+    # @param run_time_threshold [Integer] Maximum number of seconds a job is allowed to
+    #   run before an exception is raised. Set to 0 to skip this check.
+    # @param queues [Array<String>, nil] If given, only check jobs in these queues.
+    #   If `nil` (default), all queues are checked.
+    def initialize(locked_to_started_threshold: 3 * 60, run_time_threshold: 12 * 60, queues: nil)
+      @locked_to_started_threshold = locked_to_started_threshold
+      @run_time_threshold          = run_time_threshold
+      @queues                      = queues
     end
 
     # Executes the stale job detection.
@@ -38,6 +41,7 @@ module Workhorse::Jobs
       if @locked_to_started_threshold != 0
         rel = Workhorse::DbJob.locked
         rel = rel.where('locked_at < ?', @locked_to_started_threshold.seconds.ago)
+        rel = rel.where(queue: @queues) if @queues
         ids = rel.pluck(:id)
 
         unless ids.empty?
@@ -50,6 +54,7 @@ module Workhorse::Jobs
       if @run_time_threshold != 0
         rel = Workhorse::DbJob.started
         rel = rel.where('started_at < ?', @run_time_threshold.seconds.ago)
+        rel = rel.where(queue: @queues) if @queues
         ids = rel.pluck(:id)
 
         unless ids.empty?

data/lib/workhorse/poller.rb

@@ -302,6 +302,12 @@ module Workhorse
         # while we were acquiring the lock or querying jobs.
         job_ids.each { |job_id| worker.perform(job_id) } if running? && worker.accepting_jobs?
       end
+
+      # Record that this worker successfully polled. Done at the very end so it
+      # only advances when the poll actually completed (a poll that raises never
+      # reaches here). Skipped on the early return above when the worker is no
+      # longer accepting jobs, so a soft-restarting worker correctly ages out.
+      worker.heartbeat!
     end
 
     # Returns an array of {Workhorse::DbJob}s that can be started.

data/lib/workhorse/worker.rb

@@ -65,6 +65,23 @@ module Workhorse
       Rails.root.join('tmp', 'pids', "workhorse.#{pid}.shutdown")
     end
 
+    # Returns the path to the heartbeat file for a given daemon worker id.
+    #
+    # The heartbeat file is touched on every successful poll (see {#heartbeat!})
+    # and lets external monitoring determine, from its mtime, how long ago a
+    # worker last polled. It is keyed by the daemon worker id (the same id used
+    # for the pidfile) rather than the pid, so the mtime survives restarts and
+    # forms a stable per-slot "last polled at" clock.
+    #
+    # @param daemon_id [String, Integer] Daemon worker id (see
+    #   {Workhorse::Daemon}).
+    # @return [Pathname, nil] Path to heartbeat file or nil if not in Rails
+    # @private
+    def self.heartbeat_file_for(daemon_id)
+      return nil unless defined?(Rails)
+      Rails.root.join('tmp', 'pids', "workhorse.#{daemon_id}.heartbeat")
+    end
+
     # Instantiates a new worker. The worker is not automatically started.
     #
     # @param queues [Array] The queues you want this worker to process. If an
@@ -228,6 +245,28 @@ module Workhorse
       @soft_restart_requested.false?
     end
 
+    # Touches this worker's heartbeat file to record that it just polled
+    # successfully. Called at the end of each poll (see {Workhorse::Poller#poll}).
+    #
+    # Keyed by the daemon worker id provided via the
+    # `WORKHORSE_DAEMON_WORKER_ID` environment variable (set by
+    # {Workhorse::Daemon} when forking the worker). No-op when the id is absent
+    # (e.g. workers not started through the daemon) or when not running in Rails.
+    #
+    # This is best-effort: any error is swallowed so that a heartbeat failure can
+    # never take down the worker.
+    #
+    # @return [void]
+    def heartbeat!
+      daemon_id = ENV.fetch('WORKHORSE_DAEMON_WORKER_ID', nil)
+      return unless daemon_id
+
+      path = self.class.heartbeat_file_for(daemon_id)
+      FileUtils.touch(path) if path
+    rescue StandardError => e
+      Workhorse.debug_log("[Job worker #{id}] Heartbeat touch failed: #{e.class}: #{e.message}")
+    end
+
     # Schedules a job for execution in the thread pool.
     #
     # @param db_job_id [Integer] The ID of the {Workhorse::DbJob} to perform

data/lib/workhorse.rb

@@ -98,18 +98,6 @@ module Workhorse
   mattr_accessor :clean_stuck_jobs
   self.clean_stuck_jobs = false
 
-  # This setting is for {Workhorse::Jobs::DetectStaleJobsJob} and specifies the
-  # maximum number of seconds a job is allowed to stay 'locked' before this job
-  # throws an exception. Set this to 0 to skip this check.
-  mattr_accessor :stale_detection_locked_to_started_threshold
-  self.stale_detection_locked_to_started_threshold = 3 * 60
-
-  # This setting is for {Workhorse::Jobs::DetectStaleJobsJob} and specifies the
-  # maximum number of seconds a job is allowed to run before this job throws an
-  # exception. Set this to 0 to skip this check.
-  mattr_accessor :stale_detection_run_time_threshold
-  self.stale_detection_run_time_threshold = 12 * 60
-
   # Maximum memory usage per {Workhorse::Worker} process in MB.
   # When exceeded, the watch command will restart the worker. Set to 0 to disable.
   #

data/test/workhorse/worker_test.rb

@@ -306,6 +306,53 @@ class Workhorse::WorkerTest < WorkhorseTest
     Workhorse.max_worker_memory_mb = 0
   end
 
+  def test_heartbeat_file_for
+    assert_equal(
+      Rails.root.join('tmp', 'pids', 'workhorse.3.heartbeat').to_s,
+      Workhorse::Worker.heartbeat_file_for(3).to_s
+    )
+  end
+
+  def test_heartbeat_noop_without_daemon_id
+    ENV.delete('WORKHORSE_DAEMON_WORKER_ID')
+    path = Workhorse::Worker.heartbeat_file_for('42')
+    FileUtils.rm_f(path)
+
+    Workhorse::Worker.new.heartbeat!
+
+    assert_not File.exist?(path), 'heartbeat must not be touched without a daemon id'
+  ensure
+    FileUtils.rm_f(path)
+  end
+
+  def test_heartbeat_touches_file
+    ENV['WORKHORSE_DAEMON_WORKER_ID'] = '42'
+    path = Workhorse::Worker.heartbeat_file_for('42')
+    FileUtils.rm_f(path)
+
+    Workhorse::Worker.new.heartbeat!
+
+    assert File.exist?(path), 'heartbeat file expected to be touched'
+  ensure
+    ENV.delete('WORKHORSE_DAEMON_WORKER_ID')
+    FileUtils.rm_f(path)
+  end
+
+  def test_poll_touches_heartbeat
+    ENV['WORKHORSE_DAEMON_WORKER_ID'] = '42'
+    path = Workhorse::Worker.heartbeat_file_for('42')
+    FileUtils.rm_f(path)
+
+    with_worker(pool_size: 1, polling_interval: 0.1) do
+      with_retries do
+        assert File.exist?(path), 'expected a successful poll to touch the heartbeat file'
+      end
+    end
+  ensure
+    ENV.delete('WORKHORSE_DAEMON_WORKER_ID')
+    FileUtils.rm_f(path)
+  end
+
   private
 
   def assert_process(pid)

data/workhorse.gemspec

@@ -1,14 +1,14 @@
 # -*- encoding: utf-8 -*-
-# stub: workhorse 1.4.5 ruby lib
+# stub: workhorse 1.5.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "workhorse".freeze
-  s.version = "1.4.5".freeze
+  s.version = "1.5.1".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Sitrox".freeze]
-  s.date = "2026-05-09"
+  s.date = "2026-07-22"
   s.files = [".github/workflows/ruby.yml".freeze, ".gitignore".freeze, ".releaser_config".freeze, ".rubocop.yml".freeze, "CHANGELOG.md".freeze, "FAQ.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "RUBY_VERSION".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/rubocop".freeze, "lib/active_job/queue_adapters/workhorse_adapter.rb".freeze, "lib/generators/workhorse/install_generator.rb".freeze, "lib/generators/workhorse/templates/bin/workhorse.rb".freeze, "lib/generators/workhorse/templates/config/initializers/workhorse.rb".freeze, "lib/generators/workhorse/templates/create_table_jobs.rb".freeze, "lib/workhorse.rb".freeze, "lib/workhorse/active_job_extension.rb".freeze, "lib/workhorse/daemon.rb".freeze, "lib/workhorse/daemon/shell_handler.rb".freeze, "lib/workhorse/db_job.rb".freeze, "lib/workhorse/enqueuer.rb".freeze, "lib/workhorse/jobs/cleanup_succeeded_jobs.rb".freeze, "lib/workhorse/jobs/detect_stale_jobs_job.rb".freeze, "lib/workhorse/jobs/run_active_job.rb".freeze, "lib/workhorse/jobs/run_rails_op.rb".freeze, "lib/workhorse/performer.rb".freeze, "lib/workhorse/poller.rb".freeze, "lib/workhorse/pool.rb".freeze, "lib/workhorse/scoped_env.rb".freeze, "lib/workhorse/worker.rb".freeze, "test/active_job/queue_adapters/workhorse_adapter_test.rb".freeze, "test/lib/db_schema.rb".freeze, "test/lib/jobs.rb".freeze, "test/lib/test_helper.rb".freeze, "test/workhorse/daemon_test.rb".freeze, "test/workhorse/db_job_test.rb".freeze, "test/workhorse/enqueuer_test.rb".freeze, "test/workhorse/performer_test.rb".freeze, "test/workhorse/poller_test.rb".freeze, "test/workhorse/pool_test.rb".freeze, "test/workhorse/worker_test.rb".freeze, "test/workhorse/yjit_test.rb".freeze, "workhorse.gemspec".freeze]
   s.homepage = "https://github.com/sitrox/workhorse".freeze
   s.licenses = ["MIT".freeze]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: workhorse
 version: !ruby/object:Gem::Version
-  version: 1.4.5
+  version: 1.5.1
 platform: ruby
 authors:
 - Sitrox
 bindir: bin
 cert_chain: []
-date: 2026-05-09 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Multi-threaded job backend with database queuing for ruby.
 test_files: