solid_queue_guard 1.2.5 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1893e95d5ab5c66e556b93b743f0a981b62509716b11350b546941af696cf282
-  data.tar.gz: 44d23bf1b5f8900a50c84446a2abaaba97bba4689979d5f0799d148e7edee06d
+  metadata.gz: d67d9fdbc9de83d8566bfc3c7529e4be2bf3e924cba7f840b555869cd0b2a618
+  data.tar.gz: 63368e74ee06a570c18d7f7cd7ea56de72355ae84327f883a01233f1bee38cd5
 SHA512:
-  metadata.gz: 3a90a43b4541edd2f96ad9795708a016934ac6820998c83c4217be5902c8210fdf8ba0bb07ba021922cc297f58caf23a704640231fc6f65b28842d32e9bb3e79
-  data.tar.gz: 50df8d5b56540152da201bf0a71acd9cb9f8d1ae9a11b180d66f5d597e274982c54bb16bec3d82d5cc1997cd12c7fa128db983a1a10e303c4e93cc47e8b9a954
+  metadata.gz: 20bfa32ec7ae3b150414576877e57f432364f21df151082e6fd4a6d7da7c9b3802899223fcc33b37dc529b2ecf3a4723748b4a9ec30b5bd32fa168632cf73840
+  data.tar.gz: 4b1553424fb1ad718edd40f22f06cf463837fc82bcb7350efd4c062b956cfd94a7cffdeb329460afbb23f17f40f0e30243b169c314c49f8679c41ed67ea89346

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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/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/version.rb

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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.3.0
 platform: ruby
 authors:
 - Rafael Pissardo
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -393,6 +394,7 @@ metadata:
   bug_tracker_uri: https://github.com/rafael-pissardo/solid_queue_guard/issues
   documentation_uri: https://github.com/rafael-pissardo/solid_queue_guard#readme
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -407,7 +409,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.3
+signing_key:
 specification_version: 4
 summary: Production readiness checks and runtime guards for Rails Solid Queue.
 test_files: []