sidekiq-throttled 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85023f0d147ed5c41ac214b6f8c907ac4fd8c023271e0def9297659305449b16
-  data.tar.gz: 2f6b2c9c97210185dc91539328b85e108ee07b36770da7eaf87e27d3cff4138c
+  metadata.gz: dcec267e317bfaeabe891a21b776cbddc083cba27a163c82a5e5e0839390fb8d
+  data.tar.gz: '09706d9f91fdc770f01a5fb7835d8c35706c2852dfe798ec3e60dcd76bdeb8e9'
 SHA512:
-  metadata.gz: 9fe961d74fd88be00803879e6a35197be285a80d7d7c289385bf6268a1c58c9e82a81c32ef0fb89070f8eccab6dc8ee963de2b2109695879be0c4b7d75bdc770
-  data.tar.gz: ee02663fa70432081fefbb756b5be9a72917ef3dcee1cf915a221d97c21f7ceb65b04ac0a54d5a3dba0709a484361e04423e3cf7a0750ef7127df5d0d1796f92
+  metadata.gz: 4c90a776bb731f2a140469a03092e8307997602d7723f73517ed804f0f3973cbfed9692baf8f0f98e47320e0b5c4316bbaa15ffc36c70637d68d553e9a537d25
+  data.tar.gz: e52c211802a6e740dcd8b1b77ef3d7cad8b39d6a5aa714b7f1619c9ec2391d893140a636562cb6bafdc326ce4bcbd42904bfe053e6410ceec215720d72100b4a

data/README.adoc

@@ -79,6 +79,30 @@ class MyWorker
 end
 ----
 
+=== Requeue Strategy
+The default requeue strategy `:enqueue` puts jobs immiediately back on the queue if they are being limited, with a potential `cooldown_period`. This is often an appropriate strategy but in some situations may cause the system to repeatedly dequeue and reenque the same job causing excessive redis CPU usage.
+
+An alternative requeue strategy `:schedule` is available that schedules the work for the future. This can be less appropriate for highly concurrent jobs, but may be a good way to reduce redis load when the number of jobs to be processed is modest.
+
+The alternative `:schedule` strategy may be configured globally with `config.default_requeue_options = { with: :schedule }`
+
+It may be configured on a per job basis with:
+
+```ruby
+  sidekiq_throttle(
+    # Allow 5 jobs to processed within 1 minute, using the 
+    threshold: { limit: 5, period: 1.minute, requeue: {with: :schedule} }
+  )
+```
+
+It is also possible to requeue jobs to another queue:
+
+```ruby
+  sidekiq_throttle(
+    # Allow 5 jobs to processed within 1 minute, using the 
+    threshold: { limit: 5, period: 1.minute, requeue: {to: :other_queue, with: :schedule} }
+  )
+```
 
 === Web UI
 
@@ -246,8 +270,8 @@ class MyJob
   sidekiq_throttle(
     # Allow maximum 10 concurrent jobs per project at a time and maximum 2 jobs per user
     concurrency: [
-      { limit: 10, key_suffix: -> (project_id, user_id) { project_id } },
-      { limit: 2, key_suffix: -> (project_id, user_id) { user_id } }
+      { limit: 10, key_suffix: -> (project_id, user_id) { "project_id:#{project_id}" } },
+      { limit: 2, key_suffix: -> (project_id, user_id) { "user_id:#{user_id}" } }
     ]
     # For :threshold it works the same
   )
@@ -309,6 +333,47 @@ lock TTL to fit your needs:
 sidekiq_throttle(concurrency: { limit: 20, ttl: 1.hour.to_i })
 ----
 
+=== Scheduling based concurrency tuning
+
+The default concurrency throttling algorithm immediately requeues throttled
+jobs. This can lead to a lot of wasted work picking up the same set of still
+throttled jobs repeatedly. This churn also often starves lower priority
+jobs/queues. The `:schedule` requeue strategy delays checking the runability of
+throttled jobs until likely to be runnable. This future time is estimated based
+on the expected runtime of the job and current number of throttled jobs. This
+eliminates -- or greatly reduces -- the negative impacts to non-throttled job
+types and queues and reduces wasted work constantly rechecking the same still
+throttled jobs.
+
+**Config items**
+
+- `limit` — Maximum number of this job allowed to run simultaneously.
+- `avg_job_duration` — Expected runtime (in seconds) for this job type.  
+  Choose a value on the high end of what’s plausible; if you set this too low under heavy load, job scheduling will become sub-optimal.
+- `lost_job_threshold` — Duration (in seconds) representing how long a job “owns” its concurrency slot before being considered lost.
+- `ttl` — Deprecated alias for `lost_job_threshold`.
+- `max_delay` — The maximum number of seconds to delay a job when it is throttled.  
+  Prevents excessively long scheduling delays as the backlog grows.  
+  _Default: the smaller of 30 minutes or `10 × avg_job_duration`._
+
+[source,ruby]
+----
+sidekiq_throttle(
+  concurrency: {
+    # only run 10 of this job at a time 
+    limit: 10,
+    # these jobs finish in less than 30 seconds 
+    avg_job_duration: 30,
+    # if it doesn't release its lease in 2 minutes it's considered lost
+    lost_job_threshold: 120,
+    # maximum delay allowed when throttled
+    max_delay: 300
+  },
+  # requeue using Sidekiq's scheduler
+  requeue: { with: :schedule }
+)
+----
+
 
 == Supported Ruby Versions
 
@@ -317,6 +382,7 @@ This library aims to support and is tested against the following Ruby versions:
 * Ruby 3.2.x
 * Ruby 3.3.x
 * Ruby 3.4.x
+* Ruby 4.0.x
 
 If something doesn't work on one of these versions, it's a bug.
 
@@ -337,10 +403,12 @@ dropped.
 This library aims to support and work with following Sidekiq versions:
 
 * Sidekiq 8.0.x
+* Sidekiq 8.1.x
 
-And the following Sidekiq Pro versions:
+And (might work with) the following Sidekiq Pro versions:
 
 * Sidekiq Pro 8.0.x
+* Sidekiq Pro 8.1.x
 
 == Development
 

data/lib/sidekiq/throttled/strategy/base.rb

@@ -14,7 +14,11 @@ module Sidekiq
           key = @base_key.dup
           return key unless @key_suffix
 
-          key << ":#{@key_suffix.call(*job_args)}"
+          key << ":#{key_suffix(job_args)}"
+        end
+
+        def key_suffix(job_args)
+          @key_suffix.respond_to?(:call) ? @key_suffix.call(*job_args) : @key_suffix
         rescue StandardError => e
           Sidekiq.logger.error "Failed to get key suffix: #{e}"
           raise e

data/lib/sidekiq/throttled/strategy/concurrency.lua

@@ -1,16 +1,61 @@
-local key = KEYS[1]
+local in_progress_jobs_key = KEYS[1]
+local backlog_info_key = KEYS[2]
 local jid = ARGV[1]
 local lmt = tonumber(ARGV[2])
-local ttl = tonumber(ARGV[3])
+local lost_job_threshold = tonumber(ARGV[3])
 local now = tonumber(ARGV[4])
 
-redis.call("ZREMRANGEBYSCORE", key, "-inf", "(" .. now)
+-- supporting functions
+local function over_limit()
+  return lmt <= redis.call("ZCARD", in_progress_jobs_key)
+end
+
+local function job_already_in_progress()
+  return redis.call("ZSCORE", in_progress_jobs_key, jid)
+end
+
+-- Estimates current backlog size. This function tends to underestimate 
+-- the actual backlog. This is intentional. Overestimates are bad as it
+-- can cause unnecessary delays in job processing. Underestimates are much
+-- safer as they only increase workload of sidekiq processors. 
+local function est_current_backlog_size()
+  local old_size = tonumber(redis.call("HGET", backlog_info_key, "size")) or 0
+  local old_timestamp = tonumber(redis.call("HGET", backlog_info_key, "timestamp")) or now
+  
+  local jobs_lost_since_old_timestamp = (now - old_timestamp) / lost_job_threshold * lmt
+
+  return math.max(old_size - jobs_lost_since_old_timestamp, 0) 
+end
+
+
+local function change_backlog_size(delta)
+  local curr_backlog_size = est_current_backlog_size()
+
+  redis.call("HSET", backlog_info_key, "size", curr_backlog_size + delta) 
+  redis.call("HSET", backlog_info_key, "timestamp", now)
+  redis.call("EXPIRE", backlog_info_key, math.ceil((lost_job_threshold * curr_backlog_size) + 1 / lmt))
+end
+
+local function register_job_in_progress()
+  redis.call("ZADD", in_progress_jobs_key, now + lost_job_threshold , jid)
+  redis.call("EXPIRE", in_progress_jobs_key, lost_job_threshold)
+end
+
+local function clear_stale_in_progress_jobs()
+  local cleared_count = redis.call("ZREMRANGEBYSCORE", in_progress_jobs_key, "-inf", "(" .. now)
+  change_backlog_size(-cleared_count)
+end
+
+-- END supporting functions
+
+clear_stale_in_progress_jobs()
 
-if lmt <= redis.call("ZCARD", key) and not redis.call("ZSCORE", key, jid) then
+if over_limit() and not job_already_in_progress() then
+  change_backlog_size(1)
   return 1
 end
 
-redis.call("ZADD", key, now + ttl, jid)
-redis.call("EXPIRE", key, ttl)
+register_job_in_progress()
+change_backlog_size(-1)
 
 return 0

data/lib/sidekiq/throttled/strategy/concurrency.rb

@@ -26,13 +26,26 @@ module Sidekiq
         # @param [#to_s] strategy_key
         # @param [#to_i, #call] limit Amount of allowed concurrent jobs
         #   per processors running for given key.
-        # @param [#to_i] ttl Concurrency lock TTL in seconds.
+        # @param [#to_i] avg_job_duration Average number of seconds needed
+        #   to complete a job of this type. Default: 300 or 1/3 of lost_job_threshold
+        # @param [#to_i] lost_job_threshold Seconds to wait before considering
+        #   a job lost or dead. Default: 900 or 3 * avg_job_duration
         # @param [Proc] key_suffix Dynamic key suffix generator.
-        def initialize(strategy_key, limit:, ttl: 900, key_suffix: nil)
-          @base_key   = "#{strategy_key}:concurrency.v2"
-          @limit      = limit
-          @ttl        = ttl.to_i
+        # @param [#to_i] max_delay Maximum number of seconds to delay a job when it
+        #   throttled. This prevents jobs from being schedule very far in the future
+        #   when the backlog is large. Default: the smaller of 30 minutes or 10 * avg_job_duration
+        # @deprecated @param [#to_i] ttl Obsolete alias for `lost_job_threshold`.
+        #   Default: 900 or 3 * avg_job_duration
+        def initialize(strategy_key, limit:, avg_job_duration: nil, ttl: nil, # rubocop:disable Metrics/ParameterLists
+                       lost_job_threshold: ttl, key_suffix: nil, max_delay: nil)
+          @base_key = "#{strategy_key}:concurrency.v2"
+          @limit = limit
+          @avg_job_duration, @lost_job_threshold = interp_duration_args(avg_job_duration, lost_job_threshold)
           @key_suffix = key_suffix
+          @max_delay = max_delay || [(10 * @avg_job_duration), 1_800].min
+
+          raise(ArgumentError, "lost_job_threshold must be greater than avg_job_duration") if
+            @lost_job_threshold <= @avg_job_duration
         end
 
         # @return [Boolean] Whenever strategy has dynamic config
@@ -46,8 +59,8 @@ module Sidekiq
           return false unless job_limit
           return true if job_limit <= 0
 
-          keys = [key(job_args)]
-          argv = [jid.to_s, job_limit, @ttl, Time.now.to_f]
+          keys = [key(job_args), backlog_info_key(job_args)]
+          argv = [jid.to_s, job_limit, @lost_job_threshold, Time.now.to_f]
 
           Sidekiq.redis { |redis| 1 == SCRIPT.call(redis, keys: keys, argv: argv) }
         end
@@ -57,11 +70,8 @@ module Sidekiq
           job_limit = limit(job_args)
           return 0.0 if !job_limit || count(*job_args) < job_limit
 
-          oldest_jid_with_score = Sidekiq.redis { |redis| redis.zrange(key(job_args), 0, 0, withscores: true) }.first
-          return 0.0 unless oldest_jid_with_score
-
-          expiry_time = oldest_jid_with_score.last.to_f
-          expiry_time - Time.now.to_f
+          (estimated_backlog_size(job_args) * @avg_job_duration / limit(job_args))
+            .then { |delay_sec| @max_delay * (1 - Math.exp(-delay_sec / @max_delay)) } # limit to max_delay
         end
 
         # @return [Integer] Current count of jobs
@@ -78,7 +88,40 @@ module Sidekiq
         # Remove jid from the pool of jobs in progress
         # @return [void]
         def finalize!(jid, *job_args)
-          Sidekiq.redis { |conn| conn.zrem(key(job_args), jid.to_s) }
+          Sidekiq.redis do |conn|
+            conn.zrem(key(job_args), jid.to_s)
+          end
+        end
+
+        private
+
+        def backlog_info_key(job_args)
+          "#{key(job_args)}.backlog_info"
+        end
+
+        def estimated_backlog_size(job_args)
+          old_size_str, old_timestamp_str =
+            Sidekiq.redis { |conn| conn.hmget(backlog_info_key(job_args), "size", "timestamp") }
+          old_size = (old_size_str || 0).to_f
+          old_timestamp = (old_timestamp_str || Time.now).to_f
+
+          (old_size - jobs_lost_since(old_timestamp, job_args)).clamp(0, Float::INFINITY)
+        end
+
+        def jobs_lost_since(timestamp, job_args)
+          (Time.now.to_f - timestamp) / @lost_job_threshold * limit(job_args)
+        end
+
+        def interp_duration_args(avg_job_duration, lost_job_threshold)
+          if avg_job_duration && lost_job_threshold
+            [avg_job_duration.to_i, lost_job_threshold.to_i]
+          elsif avg_job_duration && lost_job_threshold.nil?
+            [avg_job_duration.to_i, avg_job_duration.to_i * 3]
+          elsif avg_job_duration.nil? && lost_job_threshold
+            [lost_job_threshold.to_i / 3, lost_job_threshold.to_i]
+          else
+            [300, 900]
+          end
         end
       end
     end

data/lib/sidekiq/throttled/version.rb

@@ -3,6 +3,6 @@
 module Sidekiq
   module Throttled
     # Gem version
-    VERSION = "2.0.0"
+    VERSION = "2.1.0"
   end
 end

data/lib/sidekiq/throttled/web/stats.rb

@@ -62,12 +62,13 @@ module Sidekiq
 
         # @return [String]
         def humanize_integer(int)
-          digits = int.to_s.chars
-          str    = digits.shift(digits.count % 3).join
-
-          str << " " << digits.shift(3).join while digits.count.positive?
-
-          str.strip
+          int.to_s.chars
+            .reverse
+            .each_slice(3)
+            .map(&:reverse)
+            .reverse
+            .map(&:join)
+            .join(",")
         end
       end
     end

data/web/views/index.html.erb

@@ -0,0 +1 @@
+index.erb

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-throttled
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Alexey Zapparov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -52,7 +51,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
-description:
 email:
 - alexey@zapparov.com
 executables: []
@@ -85,16 +83,16 @@ files:
 - lib/sidekiq/throttled/web/stats.rb
 - lib/sidekiq/throttled/worker.rb
 - web/views/index.erb
+- web/views/index.html.erb
 homepage: https://github.com/ixti/sidekiq-throttled
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ixti/sidekiq-throttled
-  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v2.0.0
+  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v2.1.0
   bug_tracker_uri: https://github.com/ixti/sidekiq-throttled/issues
-  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v2.0.0/CHANGES.md
+  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v2.1.0/CHANGES.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -109,8 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Concurrency and rate-limit throttling for Sidekiq
 test_files: []