solid_terminator 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eebd10e8944a7298814632a848c9f0d9d858591384b0787c714a5f7e958d98a2
-  data.tar.gz: 072a76c8bc904536248aa0eeb2b3ed7ed9a0bb3e9f37c24655112bcf0894b190
+  metadata.gz: 289534896466bc08b1f8a285c12c1ef406cd00a6d3941396cad7b366a20061b8
+  data.tar.gz: 8237d1db3ff4ce1e5e200ee97350936b38e62a52c9f170693d5b66d50daa9b3d
 SHA512:
-  metadata.gz: 4d6bc234cdd8edf4427e378bf155425492b45100115705ef289fba803a63fff236c7458560b00057c2e18c17384809654bca333b4e8e323f6862095e6869c720
-  data.tar.gz: 7928aa7bf48a113df6d440736556a24fb75b400e42221f57f9bda607ae952f61a4324aef4b15d4e9e5ee7eefba2b37975a22533bc2368b9f8f364f74f244781f
+  metadata.gz: 63bf381c2e3602eb6e42e373bcfa708eeab2e2c8f81fbd46eeba03f60869950501cb7670860d59e28208d6dd1983b42eddd15c4060c7f58f43147f6c58d7a7d1
+  data.tar.gz: 80eb8f57d9ff1dd4ff24658cd8575e6ebfb0a928dda0899f917f6a2da481fe6c33da6a62588858538b754a88155ccacf4791ca3d8d87582c2618370031a02b0d

data/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-10
+
+### Upgrading
+
+Run `bin/rails generate solid_terminator:update` and migrate. This adds the `arguments` column to `solid_queue_terminated_executions`.
+
+### Breaking
+
+- Requires a new migration that adds `arguments` to `solid_queue_terminated_executions` (see Upgrading). Until it runs, terminated executions are recorded without their arguments and cannot be retried. Workers log an error at startup and on every termination while the migration is missing.
+- `perform_now` on a terminated job no longer raises `SolidTerminator::JobTerminated`. `Terminable` now handles it with `rescue_from`, so the job returns normally and SolidQueue marks it finished.
+- Removed `SolidTerminator::ClaimedExecutionPatch`. SolidTerminator no longer patches SolidQueue internals.
+
+### Added
+
+- `bin/rails generate solid_terminator:update` copies only the migrations the app is missing, without touching the initializer.
+
+### Changed
+
+- Depends on `activejob`, `activerecord` and `railties` instead of the whole `rails` gem.
+
+### Fixed
+
+- `NameError: undefined local variable or method 'unblock_next_job'` raised after every job on solid_queue >= 1.5.0.
+- `SolidQueue::TerminatedExecution#retry` failed once SolidQueue cleared the finished job (immediately with `preserve_finished_jobs = false`, otherwise after `clear_finished_jobs_after`). The job's arguments are now stored on the terminated execution.
+- `SolidQueue::TerminatedExecution#retry` raised `NoMethodError: undefined method '[]' for nil` on executions recorded before 0.2.0 whose job was already cleared. It now raises `SolidQueue::TerminatedExecution::NotRetryable` with an explanation.
+- A termination could hit the wrong job: if the targeted job finished just as the monitor signalled it, `JobTerminated` could land in the next job on the same worker thread, or interrupt cleanup and leave a stale registry entry that kept signalling that thread. The monitor now raises under the registry lock, and `Terminable` only accepts the signal while the job's own code runs.
+
 ## [0.1.0] - 2026-06-06
 
 - Initial release

data/README.md

@@ -36,7 +36,7 @@ Run the install generator:
 bin/rails generate solid_terminator:install
 ```
 
-This copies two migrations and an initializer. Then run migrations.
+This copies three migrations and an initializer. Then run migrations.
 
 **Single-database apps** (SolidQueue shares the main database):
 
@@ -62,6 +62,22 @@ The generator creates two tables:
 | `solid_queue_terminations` | Termination signal — almost always empty |
 | `solid_queue_terminated_executions` | Audit trail of every terminated job |
 
+### Upgrading from 0.1
+
+Run the update generator to copy only the migrations your app is missing, then run migrations as above:
+
+```bash
+bin/rails generate solid_terminator:update
+```
+
+It takes the same `--database` option as `install`. Run it after every upgrade; when nothing is missing it does nothing.
+
+Until the migrations run, workers log an error at startup and on every termination that names this command.
+
+The migration adds an `arguments` column to `solid_queue_terminated_executions` and copies it from jobs SolidQueue still has. Terminated executions whose job SolidQueue already cleared cannot be retried.
+
+0.2 also changes behaviour: `perform_now` on a terminated job no longer raises `SolidTerminator::JobTerminated`. See the [changelog](CHANGELOG.md).
+
 ## Usage
 
 ### Make a job terminable
@@ -159,6 +175,8 @@ SolidQueue::Job.where(class_name: 'MyJob').pluck(:active_job_id)
 
 When a job is terminated, SolidTerminator writes a `SolidQueue::TerminatedExecution` record so you have a queryable audit trail.
 
+> **Note:** SolidQueue has no "terminated" state, so it records a terminated job as **finished**, the same as a job that succeeded. Mission Control and `SolidQueue::Job.finished` include terminated jobs. Use `SolidQueue::TerminatedExecution` to tell them apart.
+
 ### Query
 
 ```ruby
@@ -169,7 +187,7 @@ SolidQueue::TerminatedExecution.ordered
 SolidQueue::TerminatedExecution.where(queue_name: 'critical')
 ```
 
-Each record exposes: `job_id`, `queue_name`, `priority`, `terminated_at`.
+Each record exposes: `job_id`, `queue_name`, `priority`, `arguments`, `terminated_at`.
 
 ### Retry a terminated job
 
@@ -179,7 +197,9 @@ Re-enqueue the original job with its original arguments:
 SolidQueue::TerminatedExecution.find_by(job_id: sq_job_id).retry
 ```
 
-This destroys the `TerminatedExecution` record and enqueues a new job in a single transaction.
+This destroys the `TerminatedExecution` record and enqueues a new job in a single transaction. The job's arguments are stored on the `TerminatedExecution`, so retry still works after SolidQueue clears the finished job.
+
+Executions recorded before 0.2.0 whose job was already cleared have no `arguments`. `retry` raises `SolidQueue::TerminatedExecution::NotRetryable` for them. Delete them instead.
 
 ## Configuration
 
@@ -252,7 +272,8 @@ Planned improvements — no particular order:
 
 ```bash
 bundle install
-bundle exec rspec          # run tests
+bundle exec rspec          # run unit tests
+bundle exec rspec integration  # run against real SolidQueue models
 bundle exec rubocop        # lint
 bundle exec rubocop -A     # lint with auto-fix
 ```

data/lib/generators/solid_terminator/install_generator.rb

@@ -27,6 +27,10 @@ module SolidTerminator
         migration_template \
           'create_solid_queue_terminated_executions.rb',
           File.join(target_migrations_dir, 'create_solid_queue_terminated_executions.rb')
+
+        migration_template \
+          'add_arguments_to_solid_queue_terminated_executions.rb',
+          File.join(target_migrations_dir, 'add_arguments_to_solid_queue_terminated_executions.rb')
       end
 
       def create_initializer

data/lib/generators/solid_terminator/templates/add_arguments_to_solid_queue_terminated_executions.rb

@@ -0,0 +1,18 @@
+class AddArgumentsToSolidQueueTerminatedExecutions < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :solid_queue_terminated_executions, :arguments, :text
+
+    # Copy from jobs SolidQueue has not cleared yet; rows whose job is already gone stay NULL and cannot be retried.
+    execute <<~SQL
+      UPDATE solid_queue_terminated_executions
+      SET arguments = (
+        SELECT solid_queue_jobs.arguments FROM solid_queue_jobs
+        WHERE solid_queue_jobs.id = solid_queue_terminated_executions.job_id
+      )
+    SQL
+  end
+
+  def down
+    remove_column :solid_queue_terminated_executions, :arguments
+  end
+end

data/lib/generators/solid_terminator/update_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'install_generator'
+
+module SolidTerminator
+  module Generators
+    class UpdateGenerator < InstallGenerator
+      source_root File.expand_path('templates', __dir__)
+
+      remove_command :create_initializer
+
+      private
+
+      def migration_template(source, destination, config = {})
+        super(source, destination, config.merge(skip: true))
+      end
+    end
+  end
+end

data/lib/solid_terminator/engine.rb

@@ -7,14 +7,15 @@ module SolidTerminator
     config.to_prepare do
       require 'solid_terminator/termination'
       require 'solid_terminator/terminated_execution'
-      require 'solid_terminator/claimed_execution_patch'
-      SolidQueue::ClaimedExecution.prepend(SolidTerminator::ClaimedExecutionPatch)
     end
 
     config.after_initialize do
       if defined?(SolidQueue)
-        SolidQueue.on_worker_start { SolidTerminator.start_monitor }
-        SolidQueue.on_worker_stop  { SolidTerminator.stop_monitor }
+        SolidQueue.on_worker_start do
+          SolidQueue::TerminatedExecution.log_unless_migrated
+          SolidTerminator.start_monitor
+        end
+        SolidQueue.on_worker_stop { SolidTerminator.stop_monitor }
       end
     end
   end

data/lib/solid_terminator/job_terminated.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module SolidTerminator
+  # Inherits Exception, not StandardError, so a job's bare `rescue => e` cannot swallow termination.
   class JobTerminated < Exception; end # rubocop:disable Lint/InheritException
 end

data/lib/solid_terminator/monitor.rb

@@ -70,16 +70,10 @@ module SolidTerminator
     end
 
     def signal_termination(termination)
-      thread = ThreadRegistry.thread_for(termination.active_job_id)
-      return if thread.nil?
-
-      return clean_stale_entry(termination) unless thread.alive?
-
-      logger.info("Raising termination on job #{termination.active_job_id}")
-      begin
-        thread.raise(JobTerminated, "Job #{termination.active_job_id} terminated")
-      rescue ThreadError
-        logger.warn("Thread for job #{termination.active_job_id} died before signal; will retry next poll")
+      job_id = termination.active_job_id
+      case ThreadRegistry.raise_in(job_id, JobTerminated, "Job #{job_id} terminated")
+      when :raised then logger.info("Raised termination on job #{job_id}")
+      when :dead   then clean_stale_entry(termination)
       end
       # Row stays: job's ensure deletes it on clean exit; if the job swallows the exception
       # the row persists so the monitor retries next poll rather than silently giving up.

data/lib/solid_terminator/terminable.rb

@@ -6,33 +6,47 @@ module SolidTerminator
 
     included do
       around_perform :with_termination_handling
+      # rescue_from rather than rescuing in around_perform: perform_now then returns normally, so
+      # SolidQueue marks the job finished, and after_perform callbacks from parent classes do not run.
+      rescue_from(JobTerminated) { |error| handle_job_terminated(error) }
     end
 
     private
 
-    def with_termination_handling
+    # JobTerminated is only delivered while the job's own code runs. During registration and cleanup
+    # it is deferred, so a signal cannot interrupt deregister and leave a stale entry that would make
+    # the monitor raise into the next job on this pool thread.
+    def with_termination_handling(&)
       current_thread = Thread.current
-      st_logger.debug("Job #{job_id} registered for termination monitoring")
-      ThreadRegistry.register(job_id)
-      yield
-    rescue JobTerminated => e
-      on_job_terminated(current_thread, e)
-    ensure
+      Thread.handle_interrupt(JobTerminated => :never) do
+        ThreadRegistry.register(job_id)
+        st_logger.debug("Job #{job_id} registered for termination monitoring")
+        Thread.handle_interrupt(JobTerminated => :immediate, &)
+      ensure
+        finish_termination_handling(current_thread)
+      end
+    end
+
+    def finish_termination_handling(current_thread)
       ThreadRegistry.deregister(job_id, current_thread)
       st_logger.debug("Job #{job_id} deregistered from termination monitoring")
       cleanup_termination_row
+      discard_pending_termination
     end
 
-    def on_job_terminated(current_thread, error)
-      # Deregister before cleanup so the monitor does not re-raise mid-cleanup.
-      ThreadRegistry.deregister(job_id, current_thread)
-      handle_job_terminated(error)
+    # A signal sent just before deregister is still queued. The job is over either way, so drop it
+    # instead of letting it fire after the mask lifts and mark a completed job as terminated.
+    # Unmasking delivers any queued signal; no Thread.pending_interrupt?(JobTerminated) guard
+    # because that call segfaults on Ruby 3.1 while the interrupt is pending.
+    def discard_pending_termination
+      Thread.handle_interrupt(JobTerminated => :immediate) { nil }
+    rescue JobTerminated
+      nil
     end
 
     def handle_job_terminated(error)
       st_logger.info("Job #{job_id} terminated: #{error.message}")
       SolidQueue::TerminatedExecution.record_termination(self)
-      raise
     end
 
     def cleanup_termination_row

data/lib/solid_terminator/terminated_execution.rb

@@ -2,13 +2,31 @@
 
 module SolidQueue
   class TerminatedExecution < SolidQueue::Execution
+    class NotRetryable < StandardError; end
+
+    # Copied from the job so retry still works after SolidQueue clears the finished job.
+    serialize :arguments, coder: JSON
+
     scope :ordered, -> { order(terminated_at: :desc) }
 
+    # Without the column, `serialize` keeps arguments as a virtual attribute and saves silently drop them.
+    def self.log_unless_migrated
+      return if table_exists? && column_names.include?('arguments')
+
+      SolidTerminator.configuration.logger.error(
+        'solid_queue_terminated_executions is missing migrations, so terminated jobs cannot be retried. ' \
+        'Run `bin/rails generate solid_terminator:update` and migrate.'
+      )
+    end
+
     def self.record_termination(active_job)
       sq_job = SolidQueue::Job.find_by(active_job_id: active_job.job_id)
       return nil unless sq_job
 
-      create!(job_id: sq_job.id, queue_name: sq_job.queue_name, priority: sq_job.priority, terminated_at: Time.current)
+      log_unless_migrated
+
+      create!(job_id: sq_job.id, queue_name: sq_job.queue_name, priority: sq_job.priority,
+              arguments: sq_job.arguments, terminated_at: Time.current)
     rescue StandardError => e
       SolidTerminator.configuration.logger.error(
         "Failed to record termination for job #{active_job.job_id}: #{e.class}: #{e.message}"
@@ -17,7 +35,13 @@ module SolidQueue
     end
 
     def retry
-      active_job = ActiveJob::Base.deserialize(job.arguments)
+      # Rows terminated before 0.2.0 whose job was already cleared got no arguments from the backfill.
+      if arguments.nil?
+        raise NotRetryable, "Cannot retry terminated execution #{id} (job #{job_id}): its arguments were not " \
+                            'recorded. It was terminated before solid_terminator 0.2.0 and its job is gone.'
+      end
+
+      active_job = ActiveJob::Base.deserialize(arguments)
       transaction do
         destroy!
         active_job.enqueue

data/lib/solid_terminator/thread_registry.rb

@@ -22,6 +22,21 @@ module SolidTerminator
         @mutex.synchronize { @registry[active_job_id] }
       end
 
+      # Raises under the lock so the job cannot deregister in between and let its pool thread
+      # pick up another job, which would then receive the exception instead.
+      def raise_in(active_job_id, exception_class, message)
+        @mutex.synchronize do
+          thread = @registry[active_job_id]
+          return :not_registered unless thread
+          return :dead unless thread.alive?
+
+          thread.raise(exception_class, message)
+          :raised
+        end
+      rescue ThreadError
+        :dead
+      end
+
       def active_job_ids
         @mutex.synchronize { @registry.keys.dup }
       end

data/lib/solid_terminator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidTerminator
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,17 +1,45 @@
 --- !ruby/object:Gem::Specification
 name: solid_terminator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Meszaros Istvan-Abel
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-07 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -49,11 +77,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/generators/solid_terminator/install_generator.rb
+- lib/generators/solid_terminator/templates/add_arguments_to_solid_queue_terminated_executions.rb
 - lib/generators/solid_terminator/templates/create_solid_queue_terminated_executions.rb
 - lib/generators/solid_terminator/templates/create_solid_queue_terminations.rb
 - lib/generators/solid_terminator/templates/initializer.rb
+- lib/generators/solid_terminator/update_generator.rb
 - lib/solid_terminator.rb
-- lib/solid_terminator/claimed_execution_patch.rb
 - lib/solid_terminator/configuration.rb
 - lib/solid_terminator/engine.rb
 - lib/solid_terminator/job_terminated.rb
@@ -71,7 +100,7 @@ metadata:
   source_code_uri: https://github.com/IstvanMs/solid_terminator
   bug_tracker_uri: https://github.com/IstvanMs/solid_terminator/issues
   changelog_uri: https://github.com/IstvanMs/solid_terminator/blob/main/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -87,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.27
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Terminate specific in-progress SolidQueue jobs without stopping the worker
 test_files: []

data/lib/solid_terminator/claimed_execution_patch.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module SolidTerminator
-  module ClaimedExecutionPatch
-    def perform
-      result = execute
-      handle_result(result)
-    ensure
-      unblock_next_job
-    end
-
-    private
-
-    def handle_result(result)
-      if result.success?
-        finished
-      elsif result.error.is_a?(SolidTerminator::JobTerminated)
-        finish_terminated
-      else
-        failed_with(result.error)
-        raise result.error
-      end
-    end
-
-    def finish_terminated
-      transaction do
-        job.finished!
-        destroy!
-      end
-    end
-  end
-end