good_job 4.15.0 → 4.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d07cdaddabbb6f1966833ae6f79df8a61aef3959c3209ad64ed80e8896d7d56c
-  data.tar.gz: 555fdb53f3ba29885d46ac62bc2ab59a0f9cd13186a729c188e13101e7567634
+  metadata.gz: 9b13d49cf0a8c78543c55426eaf82eafd8518bd6f9a22ab081ac1657ff129227
+  data.tar.gz: c8e21ac65881fa645409b00d496beff08b9f99cfbcefb832a01d29bcff2e760a
 SHA512:
-  metadata.gz: f4a64d532756884282a5b5ff76b5fb4bc31ceb346f104cab837ef9c946f9a8b6373ae47bfff22d4cdf7785022711b4a2c9a632eb4f8a877fd19dfd674b62a495
-  data.tar.gz: 1310d23b3386534c4c5c11f14b2bc521e877a3856371a7b7fb8700f7d03b3a23ecfcc7fa63d4e667628057e2ac6d2c9364f8688788cee8e7538a4ac7216ef1d0
+  metadata.gz: af467c3effc78f424155420005e79ffdbff6249ae7a02ef9084f94d81d8aa28920bcfbc71f46349f6e67597f73cf39f7f2f2cd7f4edd869084091e9ab962c951
+  data.tar.gz: 19732a4dbfa6c64aeddd85c721a82f94cbaf50f2e784fa04bf22d2321bb518723992535595cdcc32a172cefbb77476ea66c9e06182c640dc2dc62b0306bf2cae

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [v4.16.0](https://github.com/bensheldon/good_job/tree/v4.16.0) (2026-04-14)
+
+[Full Changelog](https://github.com/bensheldon/good_job/compare/v4.15.0...v4.16.0)
+
+**Implemented enhancements:**
+
+- Allow filtering by label on dashboard [\#1739](https://github.com/bensheldon/good_job/pull/1739) ([bensheldon](https://github.com/bensheldon))
+- Allow multiple concurrency rules per job via labels [\#1700](https://github.com/bensheldon/good_job/pull/1700) ([bscofield](https://github.com/bscofield))
+
+**Fixed bugs:**
+
+- Fix advisory lock connection stickiness in block contexts [\#1736](https://github.com/bensheldon/good_job/pull/1736) ([bensheldon](https://github.com/bensheldon))
+- Add JRuby 10 to testing matrix [\#1559](https://github.com/bensheldon/good_job/pull/1559) ([bensheldon](https://github.com/bensheldon))
+
+**Closed issues:**
+
+- Job duration misreported if interrupted [\#1723](https://github.com/bensheldon/good_job/issues/1723)
+
+**Merged pull requests:**
+
+- Use annotated git tag in release script [\#1741](https://github.com/bensheldon/good_job/pull/1741) ([bensheldon](https://github.com/bensheldon))
+- Double single-thread scheduler integration test timeout on JRuby [\#1738](https://github.com/bensheldon/good_job/pull/1738) ([bensheldon](https://github.com/bensheldon))
+- Fix JRuby test flakes for scheduler timeout and interrupted execution duration [\#1737](https://github.com/bensheldon/good_job/pull/1737) ([bensheldon](https://github.com/bensheldon))
+- Count Advisory Locks and refactor advisory lock lifecycle [\#1735](https://github.com/bensheldon/good_job/pull/1735) ([bensheldon](https://github.com/bensheldon))
+- Show interrupted execution recovery duration in dashboard [\#1733](https://github.com/bensheldon/good_job/pull/1733) ([bensheldon](https://github.com/bensheldon))
+- chore: use `merge` to avoid mutate the query object [\#1717](https://github.com/bensheldon/good_job/pull/1717) ([luizkowalski](https://github.com/luizkowalski))
+
 ## [v4.15.0](https://github.com/bensheldon/good_job/tree/v4.15.0) (2026-04-09)
 
 [Full Changelog](https://github.com/bensheldon/good_job/compare/v4.14.2...v4.15.0)

data/README.md

@@ -538,6 +538,78 @@ Labels can be used to search jobs in the Dashboard. For example, to find all job
 
 GoodJob can extend Active Job to provide limits on concurrently running jobs, either at time of _enqueue_ or at _perform_. Limiting concurrency can help prevent duplicate, double or unnecessary jobs from being enqueued, or race conditions when performing, for example when interacting with 3rd-party APIs.
 
+```ruby
+class MyJob < ApplicationJob
+  include GoodJob::ActiveJobExtensions::Concurrency
+
+  # Define one or more concurrency rules. Each rule is scoped to a label,
+  # which is a value derived from the job's arguments at enqueue time and
+  # stored on the job record. Jobs must be enqueued with the matching label
+  # via `good_job_labels:` for the rule to apply.
+  #
+  # Multiple rules can be defined; they are evaluated in order and the first
+  # exceeded rule short-circuits the rest.
+  good_job_concurrency_rule(
+    # A label that scopes this rule. Can be a static String or a Lambda/Proc
+    # invoked in the context of the job instance. The rule only applies to jobs
+    # that were enqueued with this label in `good_job_labels`.
+    label: -> { arguments.first[:user_id] },
+
+    # Maximum number of unfinished jobs with this label to allow.
+    # Can be an Integer or Lambda/Proc invoked in the context of the job.
+    total_limit: 1,
+
+    # Or, if more control is needed:
+    # Maximum number of jobs with this label to be concurrently enqueued
+    # (excludes performing jobs). Can be an Integer or Lambda/Proc.
+    enqueue_limit: 2,
+
+    # Maximum number of jobs with this label to be concurrently performed
+    # (excludes enqueued jobs). Can be an Integer or Lambda/Proc.
+    perform_limit: 1,
+
+    # Maximum number of jobs with this label to be enqueued within the time
+    # period, looking backwards from now. Must be [count, period].
+    enqueue_throttle: [10, 1.minute],
+
+    # Maximum number of jobs with this label to be performed within the time
+    # period, looking backwards from now. Must be [count, period].
+    perform_throttle: [100, 1.hour],
+
+    # Note: Under heavy load, the total number of jobs may exceed the
+    # sum of `enqueue_limit` and `perform_limit` because of race conditions
+    # caused by imperfectly disjunctive states. If you need to constrain
+    # the total number of jobs, use `total_limit` instead. See #378.
+  )
+  # Additional rules
+  good_job_concurrency_rule(...)
+  good_job_concurrency_rule(...)
+
+  def perform(user_id:)
+    # do work
+  end
+end
+```
+
+Jobs must be enqueued with the matching label for rules to take effect:
+
+```ruby
+MyJob.set(good_job_labels: [current_user.id]).perform_later(user_id: current_user.id)
+```
+
+#### How concurrency controls work
+
+GoodJob's concurrency control strategy for `perform_limit` is "optimistic retry with an incremental backoff".  The [code is readable](https://github.com/bensheldon/good_job/blob/main/lib/good_job/active_job_extensions/concurrency.rb).
+
+- "Optimistic" meaning that the implementation's performance trade-off assumes that collisions are atypical (e.g. two users enqueue the same job at the same time) rather than regular (e.g. the system enqueues thousands of colliding jobs at the same time). Depending on your concurrency requirements, you may also want to manage concurrency through the number of GoodJob threads and processes that are performing a given queue.
+- "Retry with an incremental backoff" means that when `perform_limit` is exceeded, the job will raise a `GoodJob::ActiveJobExtensions::Concurrency::ConcurrencyExceededError` which is caught by a `retry_on` handler which re-schedules the job to execute in the near future with an incremental backoff.
+- First-in-first-out job execution order is not preserved when a job is retried with incremental back-off.
+- For pessimistic usecases that collisions are expected, use number of threads/processes (e.g., `good_job --queues "serial:1;-serial:5"`) to control concurrency. It is also a good idea to use `perform_limit` as backstop.
+
+#### Legacy: `good_job_control_concurrency_with`
+
+The original concurrency interface uses a single configuration hash and scopes limits to a concurrency _key_ (a string derived from the job) stored on the job record, rather than a label. It remains fully supported.
+
 ```ruby
 class MyJob < ApplicationJob
   include GoodJob::ActiveJobExtensions::Concurrency
@@ -568,11 +640,6 @@ class MyJob < ApplicationJob
     # with two elements: the number of jobs and the time period.
     perform_throttle: [100, 1.hour],
 
-    # Note: Under heavy load, the total number of jobs may exceed the
-    # sum of `enqueue_limit` and `perform_limit` because of race conditions
-    # caused by imperfectly disjunctive states. If you need to constrain
-    # the total number of jobs, use `total_limit` instead. See #378.
-
     # A unique key to be globally locked against.
     # Can be String or Lambda/Proc that is invoked in the context of the job.
     #
@@ -606,15 +673,6 @@ job = MyJob.perform_later("Alice", version: 'v1')
 job.good_job_concurrency_key #=> "MyJob-default-Alice-v1"
 ```
 
-#### How concurrency controls work
-
-GoodJob's concurrency control strategy for `perform_limit` is "optimistic retry with an incremental backoff".  The [code is readable](https://github.com/bensheldon/good_job/blob/main/lib/good_job/active_job_extensions/concurrency.rb).
-
-- "Optimistic" meaning that the implementation's performance trade-off assumes that collisions are atypical (e.g. two users enqueue the same job at the same time) rather than regular (e.g. the system enqueues thousands of colliding jobs at the same time). Depending on your concurrency requirements, you may also want to manage concurrency through the number of GoodJob threads and processes that are performing a given queue.
-- "Retry with an incremental backoff" means that when `perform_limit` is exceeded, the job will raise a `GoodJob::ActiveJobExtensions::Concurrency::ConcurrencyExceededError` which is caught by a `retry_on` handler which re-schedules the job to execute in the near future with an incremental backoff.
-- First-in-first-out job execution order is not preserved when a job is retried with incremental back-off.
-- For pessimistic usecases that collisions are expected, use number of threads/processes (e.g., `good_job --queues "serial:1;-serial:5"`) to control concurrency. It is also a good idea to use `perform_limit` as backstop.
-
 ### Cron-style repeating/recurring jobs
 
 GoodJob can enqueue Active Job jobs on a recurring basis that can be used as a replacement for cron.

data/app/filters/good_job/base_filter.rb

@@ -52,6 +52,7 @@ module GoodJob
     def to_params(override = {})
       {
         job_class: params[:job_class],
+        label: params[:label],
         limit: params[:limit],
         queue_name: params[:queue_name],
         query: params[:query],

data/app/filters/good_job/jobs_filter.rb

@@ -23,41 +23,14 @@ module GoodJob
     end
 
     def filtered_query(filter_params = params)
-      query = base_query
-
-      query = query.job_class(filter_params[:job_class]) if filter_params[:job_class].present?
-      query = query.where(queue_name: filter_params[:queue_name]) if filter_params[:queue_name].present?
-
-      search_query = filter_params[:query]&.strip
-      if search_query.present?
-        query = if query_is_uuid_and_job_exists?(search_query)
-                  query.where(active_job_id: search_query)
-                else
-                  query.search_text(search_query)
-                end
-      end
-
-      query = query.where(cron_key: filter_params[:cron_key]) if filter_params[:cron_key].present?
-      query = query.where(finished_at: finished_since(filter_params[:finished_since])..) if filter_params[:finished_since].present?
-
-      if filter_params[:state]
-        case filter_params[:state]
-        when 'discarded'
-          query = query.discarded
-        when 'succeeded'
-          query = query.succeeded
-        when 'retried'
-          query = query.retried
-        when 'scheduled'
-          query = query.scheduled
-        when 'running'
-          query = query.running
-        when 'queued'
-          query = query.queued
-        end
-      end
-
-      query
+      base_query
+        .merge(filter_by_job_class(filter_params[:job_class]))
+        .merge(filter_by_queue_name(filter_params[:queue_name]))
+        .merge(filter_by_label(filter_params[:label]))
+        .merge(filter_by_search_query(filter_params[:query]))
+        .merge(filter_by_cron_key(filter_params[:cron_key]))
+        .merge(filter_by_finished_since(filter_params[:finished_since]))
+        .merge(filter_by_state(filter_params[:state]))
     end
 
     def filtered_count
@@ -79,6 +52,59 @@ module GoodJob
 
     private
 
+    def filter_by_job_class(job_class)
+      return {} if job_class.blank?
+
+      GoodJob::Job.job_class(job_class)
+    end
+
+    def filter_by_queue_name(queue_name)
+      return {} if queue_name.blank?
+
+      GoodJob::Job.where(queue_name: queue_name)
+    end
+
+    def filter_by_label(label)
+      return {} if label.blank?
+
+      GoodJob::Job.labeled(label)
+    end
+
+    def filter_by_search_query(query)
+      search_query = query&.strip
+      return {} if search_query.blank?
+
+      if query_is_uuid_and_job_exists?(search_query)
+        GoodJob::Job.where(active_job_id: search_query)
+      else
+        GoodJob::Job.search_text(search_query)
+      end
+    end
+
+    def filter_by_cron_key(cron_key)
+      return {} if cron_key.blank?
+
+      GoodJob::Job.where(cron_key: cron_key)
+    end
+
+    def filter_by_finished_since(since)
+      return {} if since.blank?
+
+      GoodJob::Job.where(finished_at: finished_since(since)..)
+    end
+
+    def filter_by_state(state)
+      case state
+      when 'discarded' then GoodJob::Job.discarded
+      when 'succeeded' then GoodJob::Job.succeeded
+      when 'retried'   then GoodJob::Job.retried
+      when 'scheduled' then GoodJob::Job.scheduled
+      when 'running'   then GoodJob::Job.running
+      when 'queued'    then GoodJob::Job.queued
+      else {}
+      end
+    end
+
     def query_for_records
       filtered_query
     end