solid_queue_guard 1.2.5 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1893e95d5ab5c66e556b93b743f0a981b62509716b11350b546941af696cf282
-  data.tar.gz: 44d23bf1b5f8900a50c84446a2abaaba97bba4689979d5f0799d148e7edee06d
+  metadata.gz: 437b060eb21ee49c674d1f5ddbb34471209bbecd11eef1a99a562249f134b1f1
+  data.tar.gz: 0fb8e3a58e206ee4a0b78a4c815efb7397c1d5d55e153360d7655eee21ff81fa
 SHA512:
-  metadata.gz: 3a90a43b4541edd2f96ad9795708a016934ac6820998c83c4217be5902c8210fdf8ba0bb07ba021922cc297f58caf23a704640231fc6f65b28842d32e9bb3e79
-  data.tar.gz: 50df8d5b56540152da201bf0a71acd9cb9f8d1ae9a11b180d66f5d597e274982c54bb16bec3d82d5cc1997cd12c7fa128db983a1a10e303c4e93cc47e8b9a954
+  metadata.gz: 9fd08d490a2dff9d8e4915ed2742a660433c781a3244c321097715aac51c73729c91b5ad2cbcc90200c53c336c6a5f7cd80feb3eaebd426e025426700b5f1db5
+  data.tar.gz: da19ef71cf30e339ac2576a1749064f4ae904491bc0a67fdd61a9593feea6f2a48a051d13f260d6d0f739a43ed5aaddc5b5ef51e2183f98a58b36dbfdb3888bd

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-07-31
+
+### Fixed
+
+- `thread_pool` and topology pool recommendations work with Solid Queue 1.6+, which renamed
+  `estimated_number_of_threads` to `estimated_database_pool_size`. Guard now reads whichever
+  private helper the installed gem exposes.
+
+## [1.3.0] - 2026-07-29
+
+### Changed
+
+- `process_heartbeat_config` no longer warns just because `process_heartbeat_interval` and
+  `process_alive_threshold` keep the Solid Queue defaults — the defaults now pass. The check
+  validates the relationship between the values instead: it fails when `process_alive_threshold`
+  is not above the heartbeat interval, and warns when the margin tolerates less than
+  `min_margin` heartbeats (default 2) or when Guard's `stale_process_threshold` is above
+  `process_alive_threshold`
+- `config.checks.process_heartbeat_config = { min_margin: 3 }` tunes the required margin
+
 ## [1.2.5] - 2026-07-10
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_queue_guard (1.2.5)
+    solid_queue_guard (1.3.1)
       actionpack (>= 7.1, < 9.0)
       activejob (>= 7.1, < 9.0)
       activerecord (>= 7.1, < 9.0)

data/lib/solid_queue_guard/checks/config/process_heartbeat_config_check.rb

@@ -3,26 +3,107 @@
 module SolidQueueGuard
   module Checks
     module Config
+      # Solid Queue prunes any process whose heartbeat is older than
+      # process_alive_threshold, releasing the executions it had claimed. A live
+      # worker that merely delayed a heartbeat is pruned the same way, so the
+      # threshold must leave room for more than one missed beat.
       class ProcessHeartbeatConfigCheck < Base
-        DEFAULT_HEARTBEAT_INTERVAL = 60.seconds
-        DEFAULT_ALIVE_THRESHOLD = 5.minutes
+        DEFAULT_MIN_MARGIN = 2
 
         def call
-          heartbeat_interval = SolidQueue.process_heartbeat_interval
-          alive_threshold = SolidQueue.process_alive_threshold
-
-          if heartbeat_interval == DEFAULT_HEARTBEAT_INTERVAL && alive_threshold == DEFAULT_ALIVE_THRESHOLD
-            warn(
-              'process_heartbeat_config',
-              'Process heartbeat thresholds use defaults (interval: 60s, alive: 5m)',
-              suggestion: 'Consider customizing process_alive_threshold for your deployment latency requirements'
-            )
-          else
-            pass(
-              'process_heartbeat_config',
-              "Process heartbeat interval: #{heartbeat_interval.inspect}, alive threshold: #{alive_threshold.inspect}"
-            )
-          end
+          return invalid_heartbeat_interval unless heartbeat_interval.positive?
+          return alive_threshold_too_low if alive_threshold <= heartbeat_interval
+          return margin_too_tight if margin < min_margin
+          return guard_threshold_above_alive if stale_process_threshold > alive_threshold
+
+          healthy_thresholds
+        end
+
+        private
+
+        def healthy_thresholds
+          pass(
+            check_id,
+            "Heartbeat interval: #{humanize(heartbeat_interval)}, " \
+            "alive threshold: #{humanize(alive_threshold)} (#{margin.round(1)}x margin)",
+            metadata: base_metadata
+          )
+        end
+
+        def invalid_heartbeat_interval
+          failure(
+            check_id,
+            'process_heartbeat_interval must be a positive duration',
+            suggestion: 'Set SolidQueue.process_heartbeat_interval to a positive value (default: 60 seconds)',
+            metadata: base_metadata
+          )
+        end
+
+        def alive_threshold_too_low
+          failure(
+            check_id,
+            "process_alive_threshold (#{humanize(alive_threshold)}) is not greater than " \
+            "process_heartbeat_interval (#{humanize(heartbeat_interval)})",
+            suggestion: "Raise process_alive_threshold to at least #{humanize(recommended_threshold)} " \
+                        'so a single late heartbeat does not prune a live process',
+            metadata: base_metadata
+          )
+        end
+
+        def margin_too_tight
+          warn(
+            check_id,
+            "process_alive_threshold (#{humanize(alive_threshold)}) tolerates less than " \
+            "#{min_margin} heartbeats of #{humanize(heartbeat_interval)}",
+            suggestion: "Raise process_alive_threshold to at least #{humanize(recommended_threshold)} " \
+                        'so a single late heartbeat does not release claimed jobs',
+            metadata: base_metadata
+          )
+        end
+
+        def guard_threshold_above_alive
+          warn(
+            check_id,
+            "Guard stale_process_threshold (#{humanize(stale_process_threshold)}) is above " \
+            "process_alive_threshold (#{humanize(alive_threshold)})",
+            suggestion: "Lower stale_process_threshold to at most #{humanize(alive_threshold)}; " \
+                        'Solid Queue prunes dead process rows before Guard would report them as stale',
+            metadata: base_metadata.merge(stale_process_threshold: stale_process_threshold)
+          )
+        end
+
+        def heartbeat_interval
+          @heartbeat_interval ||= SolidQueue.process_heartbeat_interval.to_i
+        end
+
+        def alive_threshold
+          @alive_threshold ||= SolidQueue.process_alive_threshold.to_i
+        end
+
+        def stale_process_threshold
+          @stale_process_threshold ||= guard_config.check_setting(
+            :stale_process, :threshold, guard_config.stale_process_threshold
+          ).to_i
+        end
+
+        def min_margin
+          @min_margin ||= check_setting(:min_margin, DEFAULT_MIN_MARGIN)
+        end
+
+        def margin
+          @margin ||= alive_threshold / heartbeat_interval.to_f
+        end
+
+        def recommended_threshold
+          heartbeat_interval * min_margin
+        end
+
+        def base_metadata
+          { heartbeat_interval: heartbeat_interval, alive_threshold: alive_threshold }
+        end
+
+        def humanize(seconds)
+          ActiveSupport::Duration.build(seconds).inspect
         end
       end
     end

data/lib/solid_queue_guard/checks/config/thread_pool_check.rb

@@ -5,7 +5,7 @@ module SolidQueueGuard
     module Config
       class ThreadPoolCheck < Base
         def call
-          required_threads = solid_queue_configuration.send(:estimated_number_of_threads)
+          required_pool = ConfigurationSizing.estimated_database_pool_size(solid_queue_configuration)
           pool_size = SolidQueue::Record.connection_pool&.size
 
           return skip('thread_pool', 'Queue database connection pool is not available') if pool_size.nil?
@@ -17,18 +17,18 @@ module SolidQueueGuard
             )
           end.max || 1
 
-          if pool_size >= required_threads
+          if pool_size >= required_pool
             pass(
               'thread_pool',
               "Worker threads: #{max_worker_threads}, queue DB pool: #{pool_size}",
-              metadata: { threads: max_worker_threads, pool: pool_size, required: required_threads }
+              metadata: { threads: max_worker_threads, pool: pool_size, required: required_pool }
             )
           else
             failure(
               'thread_pool',
               "Worker threads: #{max_worker_threads}, queue DB pool: #{pool_size}",
-              suggestion: "Increase queue DB pool to at least #{required_threads} or reduce worker threads",
-              metadata: { threads: max_worker_threads, pool: pool_size, required: required_threads }
+              suggestion: "Increase queue DB pool to at least #{required_pool} or reduce worker threads",
+              metadata: { threads: max_worker_threads, pool: pool_size, required: required_pool }
             )
           end
         end

data/lib/solid_queue_guard/configuration_sizing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  # Reads Solid Queue's estimated queue-DB pool requirement across gem versions.
+  #
+  # Solid Queue 1.6 renamed the private helper from +estimated_number_of_threads+
+  # to +estimated_database_pool_size+ (fiber workers need a different estimate).
+  # Both return the same value for classic thread workers: max capacity + 2.
+  module ConfigurationSizing
+    module_function
+
+    def estimated_database_pool_size(configuration = SolidQueue::Configuration.new)
+      if configuration.respond_to?(:estimated_database_pool_size, true)
+        configuration.send(:estimated_database_pool_size)
+      elsif configuration.respond_to?(:estimated_number_of_threads, true)
+        configuration.send(:estimated_number_of_threads)
+      else
+        raise NoMethodError,
+              'SolidQueue::Configuration has neither estimated_database_pool_size ' \
+              'nor estimated_number_of_threads'
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/recommendations/topology.rb

@@ -33,11 +33,11 @@ module SolidQueueGuard
       def pool_recommendations
         return async_pool_recommendation if PumaPluginSupport.async_supervisor_mode?
 
-        required_threads = configuration.estimated_number_of_threads
+        required_pool = ConfigurationSizing.estimated_database_pool_size(configuration)
         pool_size = SolidQueue::Record.connection_pool&.size
-        return [] if pool_size.nil? || required_threads <= pool_size
+        return [] if pool_size.nil? || required_pool <= pool_size
 
-        ["Increase queue DB pool to at least #{required_threads + 2} (currently #{pool_size})"]
+        ["Increase queue DB pool to at least #{required_pool} (currently #{pool_size})"]
       rescue StandardError
         []
       end
@@ -62,11 +62,11 @@ module SolidQueueGuard
       end
 
       def async_pool_recommendation
-        required_threads = configuration.estimated_number_of_threads
+        required_pool = ConfigurationSizing.estimated_database_pool_size(configuration)
         pool_size = SolidQueue::Record.connection_pool&.size
-        return [] if pool_size.nil? || required_threads <= pool_size
+        return [] if pool_size.nil? || required_pool <= pool_size
 
-        ["Increase queue DB pool to at least #{required_threads + 2} " \
+        ["Increase queue DB pool to at least #{required_pool} " \
          "for async supervisor mode (currently #{pool_size})"]
       rescue StandardError
         []

data/lib/solid_queue_guard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidQueueGuard
-  VERSION = '1.2.5'
+  VERSION = '1.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.3.1
 platform: ruby
 authors:
 - Rafael Pissardo
@@ -358,6 +358,7 @@ files:
 - lib/solid_queue_guard/checks/runtime/stale_process_check.rb
 - lib/solid_queue_guard/cli.rb
 - lib/solid_queue_guard/configuration.rb
+- lib/solid_queue_guard/configuration_sizing.rb
 - lib/solid_queue_guard/engine.rb
 - lib/solid_queue_guard/formatters/json.rb
 - lib/solid_queue_guard/formatters/terminal.rb