workhorse 1.3.1 → 1.4.0.rc0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8337d1efedcb53b3fd51e983fe235aa2f1e71b6cbfedad84d2becb5c292dfb1c
-  data.tar.gz: 6746a5eeb075df326794e135b0336dea076a624e20562184c687d50603c894bd
+  metadata.gz: 66d11e1801fa64ed11dbb329dd843eef6436cdd2d999abf5786ffa013f768dbe
+  data.tar.gz: d03c50b4d34f32492386ec8c20ba065ad862e7bf9e1c90b03e0641f1f0b8b4db
 SHA512:
-  metadata.gz: 55769be0e335e14684c1e6bbd108b2c9da4fee5cf42b86149a481e0cae1d4a64d542ca0119adea20d83f3f9131dd45d61daa6e88df5e3bacde86231c0bc995b9
-  data.tar.gz: da590080ffa2b5f96c1800b730babf019f115b600335a85fc41d343573765e0114eea356c09238507913c2ca1e88cd5d0e3d12742facc201e5b9c5ba1c076188
+  metadata.gz: a3fa8b847ca0d0e68112a4f5c59c34fd24955010185bd5a4c712571e0e1dd8e3340156873bd7dc61f1e1186b04d4bda9cb9d3bfdad036209e760390a43e6a127
+  data.tar.gz: ad309e55cfb166fcd95b907f75cf2a07009b8d2c49335256505a6e0f54172b44375fd7182b972806601bbd32df43b9431977367fcafe24400ae5769658a30a06

data/.rubocop.yml

@@ -2,7 +2,7 @@ AllCops:
   DisplayCopNames: true
   NewCops: enable
   SuggestExtensions: false
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 3.0
   Exclude:
     - 'local/**/*'
     - 'vendor/**/*'
@@ -122,9 +122,15 @@ Layout/LineLength:
 
 # Prefer variable_1 over variable1 for aesthetic reasons. Do not check symbols,
 # as they often need to be another case for use in external palces (e.g. :md5).
+# $0 is a Ruby special variable for the process name.
+# Test method names often contain numbers (e.g., test_issue_22).
 Naming/VariableNumber:
   EnforcedStyle: snake_case
   CheckSymbols: false
+  AllowedPatterns:
+    - '\$0'
+  Exclude:
+    - 'test/**/*'
 
 # Depending on the surrounding code, even simple if/unless clauses may be more
 # descriptive when on multiple lines.
@@ -187,3 +193,8 @@ Style/HashSyntax:
 # Allow rescue 'Exception', necessary for Workhorse
 Lint/RescueException:
   Enabled: false
+
+# check_memory returns boolean but is not a pure predicate (has side effects)
+Naming/PredicateMethod:
+  AllowedMethods:
+    - check_memory

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Workhorse Changelog
 
+## 1.4.0.rc0 - 2026-02-11
+
+* Add `soft-restart` daemon command for graceful worker restarts. Sends a
+  `USR1` signal to all workers, causing them to stop accepting new jobs and shut
+  down after completing any currently running job. The caller is not blocked
+  (fire-and-forget). Use in combination with the `watch` command (typically via
+  cron) to automatically start fresh workers after shutdown.
+
+  Sitrox reference: #140281.
+
 ## 1.3.1 - 2025-11-05
 
 * Adapt shell handler locking behavior depending on command:

data/Gemfile

@@ -11,4 +11,4 @@ gem 'minitest'
 gem 'mysql2'
 gem 'pry'
 gem 'rake'
-gem 'rubocop', '~> 1.28.0' # Latest version supported with Ruby 2.5
+gem 'rubocop', '~> 1.60'

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 - 2025 Sitrox
+Copyright (c) 2017 - 2026 Sitrox
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -241,7 +241,7 @@ For this case, the workhorse install routine automatically creates the file
 The script can be called as follows:
 
 ```bash
-RAILS_ENV=production bundle exec bin/workhorse.rb start|stop|kill|status|watch|restart|usage
+RAILS_ENV=production bundle exec bin/workhorse.rb start|stop|kill|status|watch|restart|soft-restart|usage
 ```
 
 #### Background and customization
@@ -488,6 +488,33 @@ Workhorse.setup do |config|
 end
 ```
 
+## Soft restart
+
+The `soft-restart` command provides a way to gracefully restart all worker
+processes without interrupting jobs that are currently running. It sends a
+`USR1` signal to each worker, which causes the worker to:
+
+1. Stop accepting new jobs immediately.
+2. Wait for any currently running job to complete.
+3. Shut down and create a shutdown file (`tmp/pids/workhorse.<pid>.shutdown`).
+
+The command returns immediately (fire-and-forget) and does not block the caller.
+
+**Important:** The `soft-restart` command only *stops* workers gracefully. To
+start fresh workers after shutdown, you need the `watch` command running
+(typically via cron). Without `watch`, `soft-restart` behaves like a graceful
+stop with no automatic recovery.
+
+Example usage:
+
+```bash
+# Trigger soft restart
+RAILS_ENV=production bundle exec bin/workhorse.rb soft-restart
+
+# The watch command (e.g. via cron) will automatically start fresh workers
+*/1 * * * * cd /my/app && RAILS_ENV=production bundle exec bin/workhorse.rb watch
+```
+
 ## Load hooks
 
 Using the load hook `:workhorse_db_job`, you can inject custom code into the

data/VERSION

@@ -1 +1 @@
-1.3.1
+1.4.0.rc0

data/lib/workhorse/daemon/shell_handler.rb

@@ -1,7 +1,7 @@
 module Workhorse
   class Daemon::ShellHandler
     def self.run(**options, &block)
-      unless ARGV.count == 1
+      unless ARGV.one?
         usage
         exit 99
       end
@@ -34,6 +34,9 @@ module Workhorse
         when 'restart-logging'
           lockfile = acquire_lock(lockfile_path, File::LOCK_EX)
           status = daemon.restart_logging
+        when 'soft-restart'
+          lockfile = acquire_lock(lockfile_path, File::LOCK_EX)
+          status = daemon.soft_restart
         when 'usage'
           usage
           status = 0
@@ -52,7 +55,7 @@ module Workhorse
 
     def self.usage
       warn <<~USAGE
-        Usage: #{$PROGRAM_NAME} start|stop|status|watch|restart|usage
+        Usage: #{$PROGRAM_NAME} start|stop|status|watch|restart|soft-restart|usage
 
         Options:
 
@@ -80,6 +83,14 @@ module Workhorse
             Re-opens log files, useful e.g. after the log files have been moved or
             removed by log rotation.
 
+          soft-restart
+            Signals workers to restart gracefully. Idle workers restart
+            immediately; busy workers finish their current job first. Returns
+            immediately (fire-and-forget).
+            NOTE: Requires 'watch' (typically via cron) to start fresh workers.
+            Without 'watch', this behaves like a graceful stop with no automatic
+            recovery.
+
           usage
             Show this message
 
@@ -91,8 +102,6 @@ module Workhorse
       USAGE
     end
 
-    private
-
     def self.acquire_lock(lockfile_path, flags)
       if Workhorse.lock_shell_commands
         lockfile = File.open(lockfile_path, 'a')
@@ -103,5 +112,6 @@ module Workhorse
 
       return nil
     end
+    private_class_method :acquire_lock
   end
 end

data/lib/workhorse/daemon.rb

@@ -214,6 +214,32 @@ module Workhorse
       return code
     end
 
+    # Sends USR1 signal to all workers to initiate a soft restart.
+    # Workers will finish their current jobs before shutting down.
+    # The watch mechanism will then start fresh workers.
+    # This method returns immediately (fire-and-forget).
+    #
+    # @return [Integer] Exit code (0 = success, 2 = some signals failed)
+    def soft_restart
+      code = 0
+
+      for_each_worker do |worker|
+        _pid_file, pid, active = read_pid(worker)
+
+        next unless pid && active
+
+        begin
+          Process.kill 'USR1', pid
+          puts "Worker (#{worker.name}) ##{worker.id}: Sent soft-restart signal"
+        rescue Errno::ESRCH
+          warn "Worker (#{worker.name}) ##{worker.id}: Process not found"
+          code = 2
+        end
+      end
+
+      return code
+    end
+
     private
 
     # Executes the given block for each defined worker.
@@ -236,8 +262,8 @@ module Workhorse
       pid = fork do
         $0 = process_name(worker)
         # Reopen pipes to prevent #107576
-        $stdin.reopen File.open('/dev/null', 'r')
-        null_out = File.open '/dev/null', 'w'
+        $stdin.reopen File.open(File::NULL, 'r')
+        null_out = File.open File::NULL, 'w'
         $stdout.reopen null_out
         $stderr.reopen null_out
 

data/lib/workhorse/db_job.rb

@@ -19,7 +19,7 @@ module Workhorse
     STATE_SUCCEEDED = :succeeded
     STATE_FAILED    = :failed
 
-    EXP_LOCKED_BY = /^(.*?)\.(\d+?)\.([^.]+)$/.freeze
+    EXP_LOCKED_BY = /^(.*?)\.(\d+?)\.([^.]+)$/
 
     if respond_to?(:attr_accessible)
       attr_accessible :queue, :priority, :perform_at, :handler, :description

data/lib/workhorse/poller.rb

@@ -253,9 +253,11 @@ module Workhorse
     # @return [void]
     # @private
     def poll
+      return unless worker.accepting_jobs?
+
       @instant_repoll.make_false
 
-      timeout = [MIN_LOCK_TIMEOUT, [MAX_LOCK_TIMEOUT, worker.polling_interval].min].max
+      timeout = worker.polling_interval.clamp(MIN_LOCK_TIMEOUT, MAX_LOCK_TIMEOUT)
       with_global_lock timeout: timeout do
         job_ids = []
 
@@ -277,8 +279,8 @@ module Workhorse
             end
           end
 
-          unless running?
-            worker.log 'Rolling back transaction to unlock jobs, as worker has been shut down in the meantime'
+          unless running? && worker.accepting_jobs?
+            worker.log 'Rolling back transaction to unlock jobs, as worker is no longer accepting jobs'
             fail ActiveRecord::Rollback
           end
         end
@@ -288,7 +290,9 @@ module Workhorse
         # non-blocking and thus directly conclude the block and the transaction,
         # there would still be a risk that the transaction is not committed yet
         # when the job starts.
-        job_ids.each { |job_id| worker.perform(job_id) } if running?
+        # Also check accepting_jobs? to prevent posting if soft restart was requested
+        # while we were acquiring the lock or querying jobs.
+        job_ids.each { |job_id| worker.perform(job_id) } if running? && worker.accepting_jobs?
       end
     end
 

data/lib/workhorse/scoped_env.rb

@@ -16,16 +16,15 @@ module Workhorse
     end
 
     # Handles method delegation to the configured objects.
+    # Uses argument forwarding to pass all arguments to the delegated method.
     #
     # @param symbol [Symbol] Method name
-    # @param args [Array] Method arguments
-    # @param block [Proc, nil] Block to pass to the method
     # @return [Object] Result of the delegated method call
-    def method_missing(symbol, *args, &block)
+    def method_missing(symbol, ...)
       if @methods.include?(symbol)
-        @delegation_object.send(symbol, *args, &block)
+        @delegation_object.send(symbol, ...)
       elsif @backup_binding.try(:respond_to?, symbol)
-        @backup_binding.send(symbol, *args, &block)
+        @backup_binding.send(symbol, ...)
       else
         super
       end

data/lib/workhorse/worker.rb

@@ -21,6 +21,7 @@ module Workhorse
     LOG_LEVELS = %i[fatal error warn info debug].freeze
     SHUTDOWN_SIGNALS = %w[TERM INT].freeze
     LOG_REOPEN_SIGNAL = 'HUP'.freeze
+    SOFT_RESTART_SIGNAL = 'USR1'.freeze
 
     # @return [Array<Symbol>] The queues this worker processes
     attr_reader :queues
@@ -97,6 +98,7 @@ module Workhorse
       @pool = Pool.new(@pool_size)
       @poller = Workhorse::Poller.new(self, proc { check_memory })
       @logger = logger
+      @soft_restart_requested = Concurrent::AtomicBoolean.new(false)
 
       unless (@polling_interval / 0.1).round(2).modulo(1).zero?
         fail 'Polling interval must be a multiple of 0.1.'
@@ -158,6 +160,7 @@ module Workhorse
 
         trap_termination if @auto_terminate
         trap_log_reopen
+        trap_soft_restart
       end
     end
 
@@ -213,6 +216,14 @@ module Workhorse
       @pool.idle
     end
 
+    # Returns whether this worker is accepting new jobs.
+    # Returns false when a soft restart has been requested.
+    #
+    # @return [Boolean] True if accepting jobs, false otherwise
+    def accepting_jobs?
+      @soft_restart_requested.false?
+    end
+
     # Schedules a job for execution in the thread pool.
     #
     # @param db_job_id [Integer] The ID of the {Workhorse::DbJob} to perform
@@ -260,8 +271,8 @@ module Workhorse
         FileUtils.touch self.class.shutdown_file_for(pid)
       end
 
-      log "Worker process #{id.inspect} memory consumption (RSS) of #{mem}MB exceeds "\
-          "configured per-worker limit of #{max}MB and is now being shut down. Make sure "\
+      log "Worker process #{id.inspect} memory consumption (RSS) of #{mem}MB exceeds " \
+          "configured per-worker limit of #{max}MB and is now being shut down. Make sure " \
           'that your worker processes are watched (e.g. using the "watch"-command) for ' \
           'this worker to be restarted automatically.'
 
@@ -273,7 +284,7 @@ module Workhorse
     # @return [Integer, nil] Memory usage in MB or nil if unable to determine
     # @private
     def current_memory_consumption
-      mem = `ps -p #{pid} -o rss=`&.strip
+      mem = `ps -p #{pid} -o rss=`.strip
       return nil if mem.blank?
       return mem.to_i / 1024
     end
@@ -312,5 +323,73 @@ module Workhorse
         end
       end
     end
+
+    # Initiates a soft restart of the worker.
+    # Creates a shutdown file for the watch mechanism, then waits for all
+    # currently running jobs to complete before shutting down.
+    # This method returns immediately; shutdown happens asynchronously.
+    #
+    # @return [void]
+    # @private
+    def soft_restart
+      return if @state == :shutdown
+
+      return unless @soft_restart_requested.make_true
+
+      # Create shutdown file for watch to detect
+      shutdown_file = self.class.shutdown_file_for(pid)
+      FileUtils.touch(shutdown_file) if shutdown_file
+
+      # Monitor in a separate thread to avoid blocking the signal handler
+      @soft_restart_thread = Thread.new do
+        begin
+          wait_for_idle_then_shutdown
+        rescue Exception => e
+          log %(Soft restart error: #{e.message}\n#{e.backtrace.join("\n")}), :error
+          Workhorse.on_exception.call(e)
+        end
+      end
+    end
+
+    # Sets up signal handler for soft restart (USR1 signal).
+    #
+    # @return [void]
+    # @private
+    def trap_soft_restart
+      Signal.trap(SOFT_RESTART_SIGNAL) do
+        # Start a new thread as certain functionality (such as logging) is not
+        # available from within a trap context.
+        Thread.new do
+          begin
+            log "\nCaught #{SOFT_RESTART_SIGNAL}, initiating soft restart..."
+            soft_restart
+          rescue Exception => e
+            log %(Soft restart signal handler error: #{e.message}\n#{e.backtrace.join("\n")}), :error
+            Workhorse.on_exception.call(e)
+          end
+        end
+        # Note: Unlike trap_termination, we don't join here because soft_restart
+        # is designed to be fire-and-forget (it spawns its own monitoring thread).
+      end
+    end
+
+    # Waits for all jobs to complete, then shuts down the worker.
+    # Called asynchronously from soft_restart.
+    #
+    # @return [void]
+    # @private
+    def wait_for_idle_then_shutdown
+      loop do
+        break if @state == :shutdown
+
+        if idle == @pool_size
+          log 'All jobs completed, shutting down for soft restart'
+          shutdown
+          break
+        end
+
+        Kernel.sleep 0.2
+      end
+    end
   end
 end

data/test/active_job/queue_adapters/workhorse_adapter_test.rb

@@ -58,22 +58,22 @@ class ActiveJob::QueueAdapters::WorkhorseAdapterTest < WorkhorseTest
   end
 
   def test_wait
-    Job2.set(wait: 2.seconds).perform_later 'foo'
+    Job2.set(wait: 0.5.seconds).perform_later 'foo'
 
-    work 1, polling_interval: 0.1
+    work 0.3, polling_interval: 0.1
     assert_equal 'waiting', Workhorse::DbJob.first.state
 
-    work 2.5, polling_interval: 0.1
+    work 0.5, polling_interval: 0.1
     assert_equal 'succeeded', Workhorse::DbJob.first.reload.state
   end
 
   def test_wait_until
-    Job2.set(wait_until: (Time.now + 2.seconds)).perform_later 'foo'
+    Job2.set(wait_until: (Time.now + 0.5.seconds)).perform_later 'foo'
 
-    work 0.5, polling_interval: 0.1
+    work 0.3, polling_interval: 0.1
     assert_equal 'waiting', Workhorse::DbJob.first.state
 
-    work 3, polling_interval: 0.1
+    work 0.5, polling_interval: 0.1
     assert_equal 'succeeded', Workhorse::DbJob.first.reload.state
   end
 

data/test/lib/test_helper.rb

@@ -79,6 +79,21 @@ class WorkhorseTest < ActiveSupport::TestCase
     end
   end
 
+  def wait_for_process_exit(pid, timeout: 5)
+    deadline = Time.now + timeout
+    loop do
+      Process.getpgid(pid)
+      if Time.now > deadline
+        fail "Process #{pid} did not exit within #{timeout} seconds"
+      end
+
+      sleep 0.01
+      Thread.pass # Give detach threads a chance to reap zombies
+    rescue Errno::ESRCH
+      return # Process is fully gone from process table
+    end
+  end
+
   def capture_log(level: :debug)
     io = StringIO.new
     logger = Logger.new(io, level: level)
@@ -146,6 +161,13 @@ class WorkhorseTest < ActiveSupport::TestCase
     end
   end
 
+  def process?(pid)
+    Process.kill(0, pid)
+    true
+  rescue Errno::EPERM, Errno::ESRCH
+    false
+  end
+
   def capture_stderr
     old = $stderr
     $stderr = StringIO.new

data/test/workhorse/daemon_test.rb

@@ -83,6 +83,79 @@ class Workhorse::DaemonTest < WorkhorseTest
     assert_not File.exist?("tmp/pids/workhorse.#{daemon.workers.first.pid}.shutdown")
   end
 
+  def test_soft_restart_returns_immediately
+    with_daemon 2 do
+      # Give workers time to fully start and register signal handlers
+      sleep 0.5
+
+      result = nil
+      elapsed = Benchmark.measure { result = daemon.soft_restart }.real
+      assert_equal 0, result
+      assert elapsed < 0.1, "soft_restart should return immediately, took #{elapsed}s"
+
+      # Wait for shutdown to complete before test cleanup
+      daemon.workers.each do |w|
+        with_retries(150) { assert_not process?(w.pid) }
+      end
+    end
+  end
+
+  def test_soft_restart_creates_shutdown_files_and_watch_restarts
+    with_daemon 2 do
+      old_pids = daemon.workers.map(&:pid)
+
+      # Give workers time to fully start and register signal handlers
+      sleep 0.5
+
+      daemon.soft_restart
+
+      # Wait for each worker to create shutdown file and exit
+      old_pids.each do |pid|
+        with_retries(100) do
+          assert File.exist?("tmp/pids/workhorse.#{pid}.shutdown"),
+                 "Shutdown file for PID #{pid} should exist. Files: #{Dir['tmp/pids/*'].join(', ')}"
+        end
+        with_retries(100) do
+          assert_not process?(pid), "Process #{pid} should have exited"
+        end
+      end
+
+      # Watch should restart them and clean up shutdown files
+      capture_stderr { daemon.watch }
+
+      with_retries do
+        old_pids.each do |pid|
+          assert_not File.exist?("tmp/pids/workhorse.#{pid}.shutdown"),
+                     "Shutdown file for PID #{pid} should be cleaned up"
+        end
+
+        # Workers should be running again with different PIDs
+        assert_equal 0, daemon.status(quiet: true)
+        new_pids = daemon.workers.map(&:pid)
+        assert_empty(old_pids & new_pids, 'New workers should have different PIDs than old workers')
+      end
+    end
+  end
+
+  def test_soft_restart_with_dead_worker
+    with_daemon 2 do
+      # Give workers time to fully start and register signal handlers
+      sleep 0.5
+
+      # Kill first worker so it's dead when we try to soft_restart
+      Process.kill 'KILL', daemon.workers.first.pid
+      with_retries { assert_not process?(daemon.workers.first.pid) }
+
+      # soft_restart returns 0 because read_pid detects the dead worker as
+      # inactive and skips it (the ESRCH rescue is never reached)
+      result = daemon.soft_restart
+      assert_equal 0, result
+
+      # Second worker should still soft-restart successfully
+      with_retries(150) { assert_not process?(daemon.workers.second.pid) }
+    end
+  end
+
   private
 
   def assert_watch_output(*expected_lines)

data/test/workhorse/poller_test.rb

@@ -115,37 +115,37 @@ class Workhorse::PollerTest < WorkhorseTest
   end
 
   def test_already_locked_issue
-    # Create 100 jobs
-    100.times do |i|
+    # Create 50 jobs
+    50.times do |i|
       Workhorse.enqueue BasicJob.new(some_param: i, sleep_time: 0)
     end
 
-    # Create 25 worker processes that work for 10s each
-    25.times do
+    # Create 10 worker processes that work for 3s each
+    10.times do
       Process.fork do
-        work 10, pool_size: 1, polling_interval: 0.1
+        work 3, pool_size: 1, polling_interval: 0.1
       end
     end
 
-    # Create additional 100 jobs that are scheduled while the workers are
+    # Create additional 50 jobs that are scheduled while the workers are
     # already polling (to make sure those are picked up as well)
-    100.times do
-      sleep 0.05
+    50.times do
+      sleep 0.02
       Workhorse.enqueue BasicJob.new(sleep_time: 0)
     end
 
-    # Wait for all forked processes to finish (should take ~10s)
+    # Wait for all forked processes to finish (should take ~3s)
     Process.waitall
 
     total = Workhorse::DbJob.count
     succeeded = Workhorse::DbJob.succeeded.count
     used_workers = Workhorse::DbJob.lock.pluck(:locked_by).uniq.size
 
-    # Make sure there are 200 jobs, all jobs have succeeded and that all of the
+    # Make sure there are 100 jobs, all jobs have succeeded and that all of the
     # workers have had their turn.
-    assert_equal 200, total
-    assert_equal 200, succeeded
-    assert_equal 25,  used_workers
+    assert_equal 100, total
+    assert_equal 100, succeeded
+    assert_equal 10,  used_workers
   end
 
   def test_connection_loss
@@ -251,8 +251,12 @@ class Workhorse::PollerTest < WorkhorseTest
   private
 
   def kill_deamon_workers
-    daemon.workers.each do |worker|
-      Process.kill 'KILL', worker.pid
+    pids = daemon.workers.map(&:pid)
+    pids.each do |pid|
+      Process.kill 'KILL', pid
+      # Wait for zombies to be reaped by Process.detach threads
+      # This is necessary because Process.getpgid succeeds for zombie processes
+      wait_for_process_exit(pid)
     end
   end
 

data/test/workhorse/worker_test.rb

@@ -69,6 +69,95 @@ class Workhorse::WorkerTest < WorkhorseTest
     end
   end
 
+  def test_soft_restart_when_idle
+    with_worker(pool_size: 2, polling_interval: 0.2) do |w|
+      assert w.accepting_jobs?
+
+      Process.kill 'USR1', Process.pid
+
+      with_retries { assert_equal :shutdown, w.state }
+      assert File.exist?(Workhorse::Worker.shutdown_file_for(Process.pid))
+    end
+  ensure
+    FileUtils.rm_f Workhorse::Worker.shutdown_file_for(Process.pid)
+  end
+
+  def test_soft_restart_when_busy_waits_for_job
+    with_worker(pool_size: 1, polling_interval: 0.2) do |w|
+      Workhorse.enqueue BasicJob.new(sleep_time: 0.5)
+      with_retries { assert_equal 'started', Workhorse::DbJob.first.state }
+
+      Process.kill 'USR1', Process.pid
+      sleep 0.1
+
+      # Still running but not accepting jobs
+      w.assert_state! :running
+      assert_not w.accepting_jobs?
+
+      # Wait for job to finish and worker to shut down
+      with_retries { assert_equal :shutdown, w.state }
+    end
+  ensure
+    FileUtils.rm_f Workhorse::Worker.shutdown_file_for(Process.pid)
+  end
+
+  def test_soft_restart_prevents_new_job_pickup
+    with_worker(pool_size: 1, polling_interval: 0.2) do |w|
+      Workhorse.enqueue BasicJob.new(sleep_time: 0.4)
+      with_retries { assert_equal 'started', Workhorse::DbJob.first.state }
+
+      Process.kill 'USR1', Process.pid
+      sleep 0.1
+
+      # Enqueue another job while soft restart is pending
+      Workhorse.enqueue BasicJob.new(sleep_time: 0.1)
+
+      # Wait for worker to shut down
+      with_retries { assert_equal :shutdown, w.state }
+
+      jobs = Workhorse::DbJob.order(:id).to_a
+      assert_equal 'succeeded', jobs[0].state
+      assert_equal 'waiting', jobs[1].state # Not picked up due to soft restart
+    end
+  ensure
+    FileUtils.rm_f Workhorse::Worker.shutdown_file_for(Process.pid)
+  end
+
+  def test_soft_restart_double_signal
+    with_worker(pool_size: 1, polling_interval: 0.2) do |w|
+      Workhorse.enqueue BasicJob.new(sleep_time: 0.5)
+      with_retries { assert_equal 'started', Workhorse::DbJob.first.state }
+
+      # Send USR1 twice in rapid succession
+      Process.kill 'USR1', Process.pid
+      Process.kill 'USR1', Process.pid
+      sleep 0.1
+
+      assert_not w.accepting_jobs?
+
+      # Worker should still shut down cleanly (no double-shutdown crash)
+      with_retries { assert_equal :shutdown, w.state }
+      assert File.exist?(Workhorse::Worker.shutdown_file_for(Process.pid))
+    end
+  ensure
+    FileUtils.rm_f Workhorse::Worker.shutdown_file_for(Process.pid)
+  end
+
+  def test_soft_restart_ignored_during_shutdown
+    with_worker(pool_size: 1, polling_interval: 0.2) do |w|
+      Process.kill 'TERM', Process.pid
+      with_retries { assert_equal :shutdown, w.state }
+
+      # Sending USR1 during shutdown should not crash or create shutdown file
+      Process.kill 'USR1', Process.pid
+      sleep 0.1
+
+      assert_not File.exist?(Workhorse::Worker.shutdown_file_for(Process.pid))
+    end
+  ensure
+    FileUtils.rm_f Workhorse::Worker.shutdown_file_for(Process.pid)
+  end
+
   def test_no_queues
     enqueue_in_multiple_queues
     work 0.2, polling_interval: 0.2
@@ -150,14 +239,14 @@ class Workhorse::WorkerTest < WorkhorseTest
   def test_order_with_priorities
     Workhorse.enqueue BasicJob.new(some_param: 6, sleep_time: 0), priority: 4
     Workhorse.enqueue BasicJob.new(some_param: 4, sleep_time: 0), priority: 3
-    sleep 1
+    sleep 0.1
     Workhorse.enqueue BasicJob.new(some_param: 5, sleep_time: 0), priority: 3
     Workhorse.enqueue BasicJob.new(some_param: 3, sleep_time: 0), priority: 2
     Workhorse.enqueue BasicJob.new(some_param: 2, sleep_time: 0), priority: 1
     Workhorse.enqueue BasicJob.new(some_param: 1, sleep_time: 0), priority: 0
 
     BasicJob.results.clear
-    work 1.3, pool_size: 1, polling_interval: 0.2
+    work 1, pool_size: 1, polling_interval: 0.1
     assert_equal (1..6).to_a, BasicJob.results
   end
 
@@ -227,13 +316,6 @@ class Workhorse::WorkerTest < WorkhorseTest
     assert_not process?(pid), "Process #{pid} expected to be stopped"
   end
 
-  def process?(pid)
-    Process.kill(0, pid)
-    true
-  rescue Errno::EPERM, Errno::ESRCH
-    false
-  end
-
   def enqueue_in_multiple_queues
     Workhorse.enqueue BasicJob.new(some_param: nil)
     Workhorse.enqueue BasicJob.new(some_param: :q1), queue: :q1

data/workhorse.gemspec

@@ -1,14 +1,14 @@
 # -*- encoding: utf-8 -*-
-# stub: workhorse 1.3.1 ruby lib
+# stub: workhorse 1.4.0.rc0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "workhorse".freeze
-  s.version = "1.3.1"
+  s.version = "1.4.0.rc0"
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Sitrox".freeze]
-  s.date = "2025-11-05"
+  s.date = "2026-02-11"
   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, "workhorse.gemspec".freeze]
   s.rubygems_version = "3.4.6".freeze
   s.summary = "Multi-threaded job backend with database queuing for ruby.".freeze

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: workhorse
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0.rc0
 platform: ruby
 authors:
 - Sitrox
 bindir: bin
 cert_chain: []
-date: 2025-11-05 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -112,11 +112,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 4.0.2
 specification_version: 4
 summary: Multi-threaded job backend with database queuing for ruby.
 test_files: