workhorse 1.5.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1159cb21bdb8fcb4a31ae5857ad5dcc16191879ac6f8025830b97cb6627df8c
-  data.tar.gz: c963ee57e992cf754cde1e91df6a93d7d207aff663b3bbdae443050605918e63
+  metadata.gz: 9ffbb2c24919d7b745fd87bd6a8675fdae5448a6c0e11c3af486d34baf5a9343
+  data.tar.gz: 9cf2270f0c3a65d244d679baf56367033e314e4a8b7ed11cc17f4d07e4a6fe63
 SHA512:
-  metadata.gz: 05b57e6750c6bdf4d693d503f0d0659f7dcb23c49c6a3f11d47ed31ba665cf5b5bae1f1aa6c6ea925fa35125260da37e9b31aeccd644e9cbefce26c50284104b
-  data.tar.gz: f9832222d5b3bd0edb56089c06a6eb1ba36ef4d496580aab83d75a75760c583dd2b74647a0d196be58b3e4f5b91096228bee0cbb7df7cfe9b6efbb7bc92bb32e
+  metadata.gz: 22b02451a64ae383b75616b9556cc05927f479f47db7d7993347df0f520d36ebfda8c7f3f4de49574c84499dfd603285bab83295df72c6100b0f6f438730d576
+  data.tar.gz: '0549ab8a2e2683dd13b60bc85a5d2d85a260dee938a13714c45fe1233af217a433af2e71f899a7056c3afd8f503f6f94e1a5b9cee5e97bbf5fb93fed9ae75a03'

data/.github/workflows/ruby.yml

@@ -16,11 +16,15 @@ jobs:
           - '3.0.1'
           - '3.1.2'
           - '3.2.1'
+        db-adapter:
+          - 'mysql2'
+          - 'trilogy'
     env:
       DB_DATABASE: workhorse
       DB_USER: root
       DB_PASSWORD: 'root'
       DB_HOST: localhost
+      DB_ADAPTER: ${{ matrix.db-adapter }}
 
     steps:
       - uses: actions/checkout@v2

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Workhorse Changelog
 
+## 1.5.2 - 2026-08-04
+
+* Fix `Poller#valid_queues` raising `NoMethodError` on the Oracle adapter. The
+  `activerecord-oracle_enhanced-adapter` returns `true` from `#execute` instead
+  of a result set, so the subsequent `.to_a` call failed with
+  `undefined method 'to_a' for true`. Switched to `#select_values`, which is
+  implemented in terms of `#exec_query` and therefore returns the queue names on
+  the `mysql2`, `trilogy` and `oracle_enhanced` adapters alike (the latter both
+  before and after version 7.0.0).
+
+  Sitrox reference: #152178.
+
+* Run the test suite against both the `mysql2` and the `trilogy` adapter. The
+  adapter can be selected using the `DB_ADAPTER` environment variable and
+  defaults to `mysql2`.
+
+## 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

data/Gemfile

@@ -12,3 +12,4 @@ gem 'mysql2'
 gem 'pry'
 gem 'rake'
 gem 'rubocop', '~> 1.60'
+gem 'trilogy'

data/VERSION

@@ -1 +1 @@
-1.5.0
+1.5.2

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/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.
@@ -446,7 +452,12 @@ module Workhorse
       select.projections = []
       queues = select.project(:queue)
 
-      return Workhorse::DbJob.connection.execute(queues.distinct.to_sql).to_a.flatten
+      # Note that `select_values` is used here on purpose: `execute` does not
+      # return a result set on every adapter (the Oracle enhanced adapter, for
+      # instance, returns `true` for queries), while `select_values` is
+      # implemented in terms of `exec_query` and thus behaves the same on the
+      # mysql2, trilogy and Oracle enhanced adapters.
+      return Workhorse::DbJob.connection.select_values(queues.distinct.to_sql)
     end
   end
 end

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/test/lib/test_helper.rb

@@ -2,11 +2,23 @@ require 'minitest/autorun'
 require 'active_record'
 require 'active_job'
 require 'pry'
-require 'mysql2'
 require 'benchmark'
 require 'concurrent'
 require 'jobs'
 
+# The adapter to run the test suite against. Both MySQL / MariaDB adapters are
+# supported, as workhorse has to work with either of them.
+DB_ADAPTER = ENV.fetch('DB_ADAPTER', 'mysql2')
+
+case DB_ADAPTER
+when 'mysql2'
+  require 'mysql2'
+when 'trilogy'
+  require 'trilogy'
+else
+  fail "Unsupported DB_ADAPTER #{DB_ADAPTER.inspect}, use 'mysql2' or 'trilogy'."
+end
+
 class MockRailsEnv < String
   def production?
     self == 'production'
@@ -43,10 +55,25 @@ class WorkhorseTest < ActiveSupport::TestCase
 
   attr_reader :daemon
 
+  # Temporarily replaces the method `method` on `object` with one that always
+  # returns `value`, for the duration of the given block.
+  #
+  # This is implemented by hand rather than using minitest's `stub`, as
+  # `minitest/mock` is not available in every minitest version this gem is
+  # tested against.
+  def with_return_value(object, method, value)
+    object.define_singleton_method(method) { |*, **| value }
+    yield
+  ensure
+    object.singleton_class.send(:remove_method, method)
+  end
+
   def clear_locks_and_db_threads!
     Workhorse::DbJob.connection.execute('SELECT RELEASE_ALL_LOCKS()')
 
-    pids = Workhorse::DbJob.connection.execute(<<~SQL.squish).to_a.flatten
+    # Use `select_values` rather than `execute`, as the latter does not return a
+    # result set on every adapter.
+    pids = Workhorse::DbJob.connection.select_values(<<~SQL.squish)
       SELECT ID FROM INFORMATION_SCHEMA.PROCESSLIST WHERE ID != CONNECTION_ID()
     SQL
 
@@ -179,7 +206,7 @@ class WorkhorseTest < ActiveSupport::TestCase
 end
 
 ActiveRecord::Base.establish_connection(
-  adapter:  'mysql2',
+  adapter:  DB_ADAPTER,
   database: ENV.fetch('DB_NAME', nil) || 'workhorse',
   username: ENV.fetch('DB_USERNAME', nil) || 'root',
   password: ENV.fetch('DB_PASSWORD', nil) || '',

data/test/workhorse/poller_test.rb

@@ -71,6 +71,21 @@ class Workhorse::PollerTest < WorkhorseTest
     assert_equal [], w.poller.send(:valid_queues)
   end
 
+  # Not every adapter returns a result set from `execute`: the Oracle enhanced
+  # adapter, for instance, returns `true` for queries, both before and after
+  # version 7.0.0. Querying the valid queues must therefore not rely on the
+  # return value of `execute`.
+  def test_valid_queues_without_usable_execute
+    w = Workhorse::Worker.new(polling_interval: 60)
+
+    Workhorse.enqueue BasicJob.new(sleep_time: 2), queue: nil
+    Workhorse.enqueue BasicJob.new(sleep_time: 2), queue: :a
+
+    with_return_value(Workhorse::DbJob.connection, :execute, true) do
+      assert_equal [nil, 'a'], w.poller.send(:valid_queues)
+    end
+  end
+
   def test_nil_queues
     w = Workhorse::Worker.new(pool_size: 2, polling_interval: 60)
 

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.5.0 ruby lib
+# stub: workhorse 1.5.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "workhorse".freeze
-  s.version = "1.5.0".freeze
+  s.version = "1.5.2".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-07-01"
+  s.date = "2026-08-04"
   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.5.0
+  version: 1.5.2
 platform: ruby
 authors:
 - Sitrox
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport