sidekiq-throttled 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 433460cfaea479faf45edc665c6f8d7d025b3e35ccdf18a32061a0b3d3c42e68
-  data.tar.gz: 4e36f4c938d7145646e04f1de6d483bdec5a4c18254c3153be3556285b779fbf
+  metadata.gz: 9d5819912372e26634558752740bc154c4d22899b42925740b86152433744740
+  data.tar.gz: dadcea04012b95e0349728c573a3253d86bae7920ee5844b1df9fb80933c2267
 SHA512:
-  metadata.gz: 3ba640f6b15fa32eb21eccda8a319357439b7367fea6c0e4d4125e0e2cd5e91fbb822768d2171c57ac0cfbe0ba640b1d21960c6e2ea317997869c8f06187aec9
-  data.tar.gz: bd28f31c6222b3f378e1e7a2d081cc9f05c4feb13b7be8b1b54ee91976a66b2263884837f3149dddcc6b047129a0311b65135433511b0dc3ed29d47ed88346ea
+  metadata.gz: cf81c1a319d6f4af5c5a06f5df95dd99ad44a405f152cfda5b4c6123d4692b93d23137ab12422d6b83c82090dc422b15b441f34ed43dc1868933d54354c1326d
+  data.tar.gz: f72803ff9a84bb3cc729869dc1105dcc9f9581c7c4c59eb2bb8a28594a7fe0df49e9b064dbae2c1f46020790637769196f98b5b38a0f77f2cb858f1b6d928679

data/README.adoc

@@ -31,7 +31,6 @@ Or install it yourself as:
 
   $ gem install sidekiq-throttled
 
-
 == Usage
 
 Add somewhere in your app's bootstrap (e.g. `config/initializers/sidekiq.rb` if
@@ -81,6 +80,17 @@ end
 ----
 
 
+=== Web UI
+
+To add a Throttled tab to your sidekiq web dashboard, require it durring your
+application initialization.
+
+[source,ruby]
+----
+require "sidekiq/throttled/web"
+----
+
+
 === Configuration
 
 [source,ruby]
@@ -89,16 +99,27 @@ Sidekiq::Throttled.configure do |config|
   # Period in seconds to exclude queue from polling in case it returned
   # {config.cooldown_threshold} amount of throttled jobs in a row. Set
   # this value to `nil` to disable cooldown manager completely.
-  # Default: 2.0
-  config.cooldown_period = 2.0
+  # Default: 1.0
+  config.cooldown_period = 1.0
 
   # Exclude queue from polling after it returned given amount of throttled
   # jobs in a row.
-  # Default: 1 (cooldown after first throttled job)
-  config.cooldown_threshold = 1
+  # Default: 100 (cooldown after hundredth throttled job in a row)
+  config.cooldown_threshold = 100
 end
 ----
 
+[WARNING]
+.Cooldown Settings
+====
+If a queue contains a thousand jobs in a row that will be throttled,
+the cooldown will kick-in 10 times in a row, meaning it will take 10 seconds
+before all those jobs are put back at the end of the queue and you actually
+start processing other jobs.
+
+You may want to adjust the cooldown_threshold and cooldown_period,
+keeping in mind that this will also impact the load on your Redis server.
+====
 
 ==== Middleware(s)
 
@@ -290,7 +311,6 @@ dropped.
 
 This library aims to support and work with following Sidekiq versions:
 
-* Sidekiq 6.5.x
 * Sidekiq 7.0.x
 * Sidekiq 7.1.x
 * Sidekiq 7.2.x
@@ -310,9 +330,9 @@ And the following Sidekiq Pro versions:
 
 === Sidekiq-Pro
 
-If you're working on Sidekiq-Pro support make sure to copy `.rspec-sidekiq-pro`
-to `.rspec-local` and that you have Sidekiq-Pro license in the global config,
-or in the `BUNDLE_GEMS\__CONTRIBSYS__COM` env variable.
+If you're working on Sidekiq-Pro support make sure that you have Sidekiq-Pro
+license set either in the global config, or in `BUNDLE_GEMS\__CONTRIBSYS__COM`
+environment variable.
 
 == Contributing
 

data/lib/sidekiq/throttled/config.rb

@@ -19,9 +19,18 @@ module Sidekiq
       # @return [Integer]
       attr_reader :cooldown_threshold
 
+      # Specifies how we should return throttled jobs to the queue so they can be executed later.
+      # Expects a hash with keys that may include :with and :to
+      # For :with, options are `:enqueue` (put them on the end of the queue) and `:schedule` (schedule for later).
+      # For :to, the name of a sidekiq queue should be specified. If none is specified, jobs will by default be
+      # requeued to the same queue they were originally enqueued in.
+      # Default: {with: `:enqueue`}
+      #
+      # @return [Hash]
+      attr_reader :default_requeue_options
+
       def initialize
-        @cooldown_period    = 2.0
-        @cooldown_threshold = 1
+        reset!
       end
 
       # @!attribute [w] cooldown_period
@@ -39,6 +48,19 @@ module Sidekiq
 
         @cooldown_threshold = value
       end
+
+      # @!attribute [w] default_requeue_options
+      def default_requeue_options=(options)
+        requeue_with = options.delete(:with).intern || :enqueue
+
+        @default_requeue_options = options.merge({ with: requeue_with })
+      end
+
+      def reset!
+        @cooldown_period    = 1.0
+        @cooldown_threshold = 100
+        @default_requeue_options = { with: :enqueue }
+      end
     end
   end
 end

data/lib/sidekiq/throttled/job.rb

@@ -13,8 +13,9 @@ module Sidekiq
     #       include Sidekiq::Job
     #       include Sidekiq::Throttled::Job
     #
-    #       sidekiq_options :queue => :my_queue
-    #       sidekiq_throttle :threshold => { :limit => 123, :period => 1.hour }
+    #       sidkiq_options :queue => :my_queue
+    #       sidekiq_throttle :threshold => { :limit => 123, :period => 1.hour },
+    #                        :requeue => { :to => :other_queue, :with => :schedule }
     #
     #       def perform
     #         # ...
@@ -23,6 +24,8 @@ module Sidekiq
     #
     # @see ClassMethods
     module Job
+      VALID_VALUES_FOR_REQUEUE_WITH = %i[enqueue schedule].freeze
+
       # Extends worker class with {ClassMethods}.
       #
       # @note Using `included` hook with extending worker with {ClassMethods}
@@ -30,6 +33,7 @@ module Sidekiq
       #
       # @private
       def self.included(base)
+        base.sidekiq_class_attribute :sidekiq_throttled_requeue_options
         base.extend(ClassMethods)
       end
 
@@ -71,9 +75,29 @@ module Sidekiq
         #       })
         #     end
         #
+        # @example Allow max 123 MyJob jobs per hour; when jobs are throttled, schedule them for later in :other_queue
+        #
+        #     class MyJob
+        #       include Sidekiq::Job
+        #       include Sidekiq::Throttled::Job
+        #
+        #       sidekiq_throttle({
+        #         :threshold => { :limit => 123, :period => 1.hour },
+        #         :requeue => { :to => :other_queue, :with => :schedule }
+        #       })
+        #     end
+        #
+        # @param [Hash] requeue What to do with jobs that are throttled
         # @see Registry.add
         # @return [void]
         def sidekiq_throttle(**kwargs)
+          requeue_options = Throttled.config.default_requeue_options.merge(kwargs.delete(:requeue) || {})
+          unless VALID_VALUES_FOR_REQUEUE_WITH.include?(requeue_options[:with])
+            raise ArgumentError, "requeue: #{requeue_options[:with]} is not a valid value for :with"
+          end
+
+          self.sidekiq_throttled_requeue_options = requeue_options
+
           Registry.add(self, **kwargs)
         end
 

data/lib/sidekiq/throttled/message.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Throttled
+    class Message
+      def initialize(item)
+        @item = item.is_a?(Hash) ? item : parse(item)
+      end
+
+      def job_class
+        @item.fetch("wrapped") { @item["class"] }
+      end
+
+      def job_args
+        @item.key?("wrapped") ? @item.dig("args", 0, "arguments") : @item["args"]
+      end
+
+      def job_id
+        @item["jid"]
+      end
+
+      private
+
+      def parse(item)
+        item = Sidekiq.load_json(item)
+        item.is_a?(Hash) ? item : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/sidekiq/throttled/middlewares/server.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 # internal
+require_relative "../message"
 require_relative "../registry"
 
 module Sidekiq
@@ -13,12 +14,11 @@ module Sidekiq
         def call(_worker, msg, _queue)
           yield
         ensure
-          job = msg.fetch("wrapped") { msg["class"] }
-          jid = msg["jid"]
+          message = Message.new(msg)
 
-          if job && jid
-            Registry.get job do |strategy|
-              strategy.finalize!(jid, *msg["args"])
+          if message.job_class && message.job_id
+            Registry.get(message.job_class) do |strategy|
+              strategy.finalize!(message.job_id, *message.job_args)
             end
           end
         end

data/lib/sidekiq/throttled/patches/basic_fetch.rb

@@ -15,17 +15,6 @@ module Sidekiq
 
         private
 
-        # Pushes job back to the head of the queue, so that job won't be tried
-        # immediately after it was requeued (in most cases).
-        #
-        # @note This is triggered when job is throttled. So it is same operation
-        #   Sidekiq performs upon `Sidekiq::Worker.perform_async` call.
-        #
-        # @return [void]
-        def requeue_throttled(work)
-          redis { |conn| conn.lpush(work.queue, work.job) }
-        end
-
         # Returns list of queues to try to fetch jobs from.
         #
         # @note It may return an empty array.

data/lib/sidekiq/throttled/patches/super_fetch.rb

@@ -14,19 +14,6 @@ module Sidekiq
 
         private
 
-        # Calls SuperFetch UnitOfWork's requeue to remove the job from the
-        # temporary queue and push job back to the head of the queue, so that
-        # the job won't be tried immediately after it was requeued (in most cases).
-        #
-        # @note This is triggered when job is throttled.
-        #
-        # @return [void]
-        def requeue_throttled(work)
-          # SuperFetch UnitOfWork's requeue will remove it from the temporary
-          # queue and then requeue it, so no acknowledgement call is needed.
-          work.requeue
-        end
-
         # Returns list of non-paused queues to try to fetch jobs from.
         #
         # @note It may return an empty array.

data/lib/sidekiq/throttled/patches/throttled_retriever.rb

@@ -12,7 +12,7 @@ module Sidekiq
 
           if work && Throttled.throttled?(work.job)
             Throttled.cooldown&.notify_throttled(work.queue)
-            requeue_throttled(work)
+            Throttled.requeue_throttled(work)
             return nil
           end
 

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

@@ -52,6 +52,16 @@ module Sidekiq
           Sidekiq.redis { |redis| 1 == SCRIPT.call(redis, keys: keys, argv: argv) }
         end
 
+        # @return [Float] How long, in seconds, before we'll next be able to take on jobs
+        def retry_in(_jid, *job_args)
+          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
+          expiry_time = oldest_jid_with_score.last.to_f
+          expiry_time - Time.now.to_f
+        end
+
         # @return [Integer] Current count of jobs
         def count(*job_args)
           Sidekiq.redis { |conn| conn.zcard(key(job_args)) }.to_i

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

@@ -69,6 +69,25 @@ module Sidekiq
           Sidekiq.redis { |redis| 1 == SCRIPT.call(redis, keys: keys, argv: argv) }
         end
 
+        # @return [Float] How long, in seconds, before we'll next be able to take on jobs
+        def retry_in(*job_args)
+          job_limit = limit(job_args)
+          return 0.0 if !job_limit || count(*job_args) < job_limit
+
+          job_period = period(job_args)
+          job_key = key(job_args)
+          time_since_oldest = Time.now.to_f - Sidekiq.redis { |redis| redis.lindex(job_key, -1) }.to_f
+          if time_since_oldest > job_period
+            # The oldest job on our list is from more than the throttling period ago,
+            # which means we have not hit the limit this period.
+            0.0
+          else
+            # If we can only have X jobs every Y minutes, then wait until Y minutes have elapsed
+            # since the oldest job on our list.
+            job_period - time_since_oldest
+          end
+        end
+
         # @return [Integer] Current count of jobs
         def count(*job_args)
           Sidekiq.redis { |conn| conn.llen(key(job_args)) }.to_i

data/lib/sidekiq/throttled/strategy.rb

@@ -31,7 +31,7 @@ module Sidekiq
       #   See keyword args of {Strategy::Threshold#initialize} for details.
       # @param [#call] key_suffix Dynamic key suffix generator.
       # @param [#call] observer Process called after throttled.
-      def initialize(name, concurrency: nil, threshold: nil, key_suffix: nil, observer: nil) # rubocop:disable Metrics/MethodLength
+      def initialize(name, concurrency: nil, threshold: nil, key_suffix: nil, observer: nil)
         @observer = observer
 
         @concurrency = StrategyCollection.new(concurrency,
@@ -44,9 +44,7 @@ module Sidekiq
           name:       name,
           key_suffix: key_suffix)
 
-        return if @concurrency.any? || @threshold.any?
-
-        raise ArgumentError, "Neither :concurrency nor :threshold given"
+        raise ArgumentError, "Neither :concurrency nor :threshold given" unless @concurrency.any? || @threshold.any?
       end
 
       # @return [Boolean] whenever strategy has dynamic config
@@ -74,18 +72,111 @@ module Sidekiq
         false
       end
 
+      # Return throttled job to be executed later. Implementation depends on the value of `with`:
+      # :enqueue means put the job back at the end of the queue immediately
+      # :schedule means schedule enqueueing the job for a later time when we expect to have capacity
+      #
+      # @param [#to_s, #call] with How to handle the throttled job
+      # @param [#to_s, #call] to Name of the queue to re-queue the job to.
+      #                          If not specified, will use the job's original queue.
+      # @return [void]
+      def requeue_throttled(work, with:, to: nil) # rubocop:disable Metrics/MethodLength
+        # Resolve :with and :to arguments, calling them if they are Procs
+        job_args = JSON.parse(work.job)["args"]
+        requeue_with = with.respond_to?(:call) ? with.call(*job_args) : with
+        target_queue = calc_target_queue(work, to)
+
+        case requeue_with
+        when :enqueue
+          re_enqueue_throttled(work, target_queue)
+        when :schedule
+          # Find out when we will next be able to execute this job, and reschedule for then.
+          reschedule_throttled(work, requeue_to: target_queue)
+        else
+          raise "unrecognized :with option #{with}"
+        end
+      end
+
       # Marks job as being processed.
       # @return [void]
       def finalize!(jid, *job_args)
         @concurrency&.finalize!(jid, *job_args)
       end
 
-      # Resets count of jobs of all avaliable strategies
+      # Resets count of jobs of all available strategies
       # @return [void]
       def reset!
         @concurrency&.reset!
         @threshold&.reset!
       end
+
+      private
+
+      def calc_target_queue(work, to) # rubocop:disable Metrics/MethodLength
+        target = case to
+                 when Proc, Method
+                   to.call(*JSON.parse(work.job)["args"])
+                 when NilClass
+                   work.queue
+                 when String, Symbol
+                   to.to_s
+                 else
+                   raise ArgumentError, "Invalid argument for `to`"
+                 end
+
+        target = work.queue if target.nil? || target.empty?
+
+        target.start_with?("queue:") ? target : "queue:#{target}"
+      end
+
+      # Push the job back to the head of the queue.
+      def re_enqueue_throttled(work, requeue_to)
+        case work.class.name
+        when "Sidekiq::Pro::SuperFetch::UnitOfWork"
+          # Calls SuperFetch UnitOfWork's requeue to remove the job from the
+          # temporary queue and push job back to the head of the target queue, so that
+          # the job won't be tried immediately after it was requeued (in most cases).
+          work.queue = requeue_to if requeue_to
+          work.requeue
+        else
+          # This is the same operation Sidekiq performs upon `Sidekiq::Worker.perform_async` call.
+          Sidekiq.redis { |conn| conn.lpush(requeue_to, work.job) }
+        end
+      end
+
+      def reschedule_throttled(work, requeue_to:)
+        message = JSON.parse(work.job)
+        job_class = message.fetch("wrapped") { message.fetch("class") { return false } }
+        job_args = message["args"]
+
+        # Re-enqueue the job to the target queue at another time as a NEW unit of work
+        # AND THEN mark this work as done, so SuperFetch doesn't think this instance is orphaned
+        # Technically, the job could processed twice if the process dies between the two lines,
+        # but your job should be idempotent anyway, right?
+        # The job running twice was already a risk with SuperFetch anyway and this doesn't really increase that risk.
+        Sidekiq::Client.enqueue_to_in(requeue_to, retry_in(work), Object.const_get(job_class), *job_args)
+        work.acknowledge
+      end
+
+      def retry_in(work)
+        message = JSON.parse(work.job)
+        jid = message.fetch("jid") { return false }
+        job_args = message["args"]
+
+        # Ask both concurrency and threshold, if relevant, how long minimum until we can retry.
+        # If we get two answers, take the longer one.
+        intervals = [@concurrency&.retry_in(jid, *job_args), @threshold&.retry_in(*job_args)].compact
+
+        raise "Cannot compute a valid retry interval" if intervals.empty?
+
+        interval = intervals.max
+
+        # Add a random amount of jitter, proportional to the length of the minimum retry time.
+        # This helps spread out jobs more evenly and avoid clumps of jobs on the queue.
+        interval += rand(interval / 5) if interval > 10
+
+        interval
+      end
     end
   end
 end

data/lib/sidekiq/throttled/strategy_collection.rb

@@ -41,6 +41,11 @@ module Sidekiq
         any? { |s| s.throttled?(...) }
       end
 
+      # @return [Float] How long, in seconds, before we'll next be able to take on jobs
+      def retry_in(*args)
+        max { |s| s.retry_in(*args) }
+      end
+
       # Marks job as being processed.
       # @return [void]
       def finalize!(...)

data/lib/sidekiq/throttled/version.rb

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

data/lib/sidekiq/throttled.rb

@@ -5,6 +5,7 @@ require "sidekiq"
 require_relative "./throttled/config"
 require_relative "./throttled/cooldown"
 require_relative "./throttled/job"
+require_relative "./throttled/message"
 require_relative "./throttled/middlewares/server"
 require_relative "./throttled/patches/basic_fetch"
 require_relative "./throttled/patches/super_fetch"
@@ -53,6 +54,11 @@ module Sidekiq
       # @return [Cooldown, nil]
       attr_reader :cooldown
 
+      # @api internal
+      #
+      # @return [Config, nil]
+      attr_reader :config
+
       # @example
       #   Sidekiq::Throttled.configure do |config|
       #     config.cooldown_period = nil # Disable queues cooldown manager
@@ -75,14 +81,11 @@ module Sidekiq
       # @param [String] message Job's JSON payload
       # @return [Boolean]
       def throttled?(message)
-        message = Sidekiq.load_json(message)
-        job     = message.fetch("wrapped") { message["class"] }
-        jid     = message["jid"]
+        message = Message.new(message)
+        return false unless message.job_class && message.job_id
 
-        return false unless job && jid
-
-        Registry.get(job) do |strategy|
-          return strategy.throttled?(jid, *message["args"])
+        Registry.get(message.job_class) do |strategy|
+          return strategy.throttled?(message.job_id, *message.job_args)
         end
 
         false
@@ -90,15 +93,16 @@ module Sidekiq
         false
       end
 
-      # @deprecated Will be removed in 2.0.0
-      def setup!
-        warn "Sidekiq::Throttled.setup! was deprecated"
+      # Return throttled job to be executed later, delegating the details of how to do that
+      # to the Strategy for that job.
+      #
+      # @return [void]
+      def requeue_throttled(work)
+        message = JSON.parse(work.job)
+        job_class = Object.const_get(message.fetch("wrapped") { message.fetch("class") { return false } })
 
-        Sidekiq.configure_server do |config|
-          config.server_middleware do |chain|
-            chain.remove(Sidekiq::Throttled::Middlewares::Server)
-            chain.add(Sidekiq::Throttled::Middlewares::Server)
-          end
+        Registry.get job_class do |strategy|
+          strategy.requeue_throttled(work, **job_class.sidekiq_throttled_requeue_options)
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-throttled
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Alexey Zapparov
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2024-01-18 00:00:00.000000000 Z
+date: 2024-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -67,6 +67,7 @@ files:
 - lib/sidekiq/throttled/errors.rb
 - lib/sidekiq/throttled/expirable_set.rb
 - lib/sidekiq/throttled/job.rb
+- lib/sidekiq/throttled/message.rb
 - lib/sidekiq/throttled/middlewares/server.rb
 - lib/sidekiq/throttled/patches/basic_fetch.rb
 - lib/sidekiq/throttled/patches/super_fetch.rb
@@ -89,9 +90,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ixti/sidekiq-throttled
-  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v1.3.0
+  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v1.5.0
   bug_tracker_uri: https://github.com/ixti/sidekiq-throttled/issues
-  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v1.3.0/CHANGES.md
+  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v1.5.0/CHANGES.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -108,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: Concurrency and rate-limit throttling for Sidekiq