sidekiq-throttled 1.0.0.alpha → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7659ca0e722a87bc85f4e9d73a38075cf005b72515bbaf06604eabaab77d8fdd
-  data.tar.gz: 28c53a85bb5d346d09d8ec08c6d23cecc687b6ec35e4c9779c07eba32bc635d6
+  metadata.gz: c7e45d38e16a4fd149ab2a5df541308d54304ae35bbd337d3701e534bffa025b
+  data.tar.gz: 7aa8a7a9469dbec0d06df4829dee111f015119861ac0caff00ca70148d014602
 SHA512:
-  metadata.gz: 2b03a9d8f51981c778c4a7b0fb84d7c20dabf902eefb00518a98a4c5a028119e820cd93920946516a51e0a399e05cf2692d12e7b59b814b37045b4dc6f852c43
-  data.tar.gz: 37478b95ae4f5426f82dceec1aa918722772c9a2c785b7c94420460b897c52cc0eee1cce02f5d03214c5d28113c3c798f5c13e31fb342ae935d92a07bc60f9b7
+  metadata.gz: 29e1a58bf302daeacb18695a618e55eec6ec177112274ac5dc85f7fbc1b14cb56c1bb8f8e9250dd22683182c8baee0d95c40f3708dba8518a5dde7cfbc71bbb6
+  data.tar.gz: 24ada7f5c9ee65400d1442feb72f95428ef9efdaf7aac2d38b732b2f4d649709712fb25d6b97e2c59627647bdcadf4c5d206fbb46f9b8321a5d293184866f2d2

data/README.adoc

@@ -89,6 +89,25 @@ end
 ----
 
 
+=== Configuration
+
+[source,ruby]
+----
+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
+
+  # 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
+end
+----
+
+
 === Observer
 
 You can specify an observer that will be called on throttling. To do so pass an
@@ -232,7 +251,6 @@ sidekiq_throttle(concurrency: { limit: 20, ttl: 1.hour.to_i })
 
 This library aims to support and is tested against the following Ruby versions:
 
-* Ruby 2.7.x
 * Ruby 3.0.x
 * Ruby 3.1.x
 * Ruby 3.2.x
@@ -255,9 +273,9 @@ 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
 
 
 == Development

data/lib/sidekiq/throttled/config.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Throttled
+    # Configuration object.
+    class Config
+      # Period in seconds to exclude queue from polling in case it returned
+      # {#cooldown_threshold} amount of throttled jobs in a row.
+      #
+      # Set this to `nil` to disable cooldown completely.
+      #
+      # @return [Float, nil]
+      attr_reader :cooldown_period
+
+      # Amount of throttled jobs returned from the queue subsequently after
+      # which queue will be excluded from polling for the durations of
+      # {#cooldown_period}.
+      #
+      # @return [Integer]
+      attr_reader :cooldown_threshold
+
+      def initialize
+        @cooldown_period    = 2.0
+        @cooldown_threshold = 1
+      end
+
+      # @!attribute [w] cooldown_period
+      def cooldown_period=(value)
+        raise TypeError, "unexpected type #{value.class}" unless value.nil? || value.is_a?(Float)
+        raise ArgumentError, "period must be positive"    unless value.nil? || value.positive?
+
+        @cooldown_period = value
+      end
+
+      # @!attribute [w] cooldown_threshold
+      def cooldown_threshold=(value)
+        raise TypeError, "unexpected type #{value.class}" unless value.is_a?(Integer)
+        raise ArgumentError, "threshold must be positive" unless value.positive?
+
+        @cooldown_threshold = value
+      end
+    end
+  end
+end

data/lib/sidekiq/throttled/cooldown.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+require_relative "./expirable_set"
+
+module Sidekiq
+  module Throttled
+    # @api internal
+    #
+    # Queues cooldown manager. Tracks list of queues that should be temporarily
+    # (for the duration of {Config#cooldown_period}) excluded from polling.
+    class Cooldown
+      class << self
+        # Returns new {Cooldown} instance if {Config#cooldown_period} is not `nil`.
+        #
+        # @param config [Config]
+        # @return [Cooldown, nil]
+        def [](config)
+          new(config) if config.cooldown_period
+        end
+      end
+
+      # @param config [Config]
+      def initialize(config)
+        @queues    = ExpirableSet.new(config.cooldown_period)
+        @threshold = config.cooldown_threshold
+        @tracker   = Concurrent::Map.new
+      end
+
+      # Notify that given queue returned job that was throttled.
+      #
+      # @param queue [String]
+      # @return [void]
+      def notify_throttled(queue)
+        @queues.add(queue) if @threshold <= @tracker.merge_pair(queue, 1, &:succ)
+      end
+
+      # Notify that given queue returned job that was not throttled.
+      #
+      # @param queue [String]
+      # @return [void]
+      def notify_admitted(queue)
+        @tracker.delete(queue)
+      end
+
+      # List of queues that should not be polled
+      #
+      # @return [Array<String>]
+      def queues
+        @queues.to_a
+      end
+    end
+  end
+end

data/lib/sidekiq/throttled/expirable_set.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Sidekiq
+  module Throttled
+    # @api internal
+    #
+    # Set of elements with expirations.
+    #
+    # @example
+    #   set = ExpirableSet.new(10.0)
+    #   set.add("a")
+    #   sleep(5)
+    #   set.add("b")
+    #   set.to_a # => ["a", "b"]
+    #   sleep(5)
+    #   set.to_a # => ["b"]
+    class ExpirableSet
+      include Enumerable
+
+      # @param ttl [Float] expiration is seconds
+      # @raise [ArgumentError] if `ttl` is not positive Float
+      def initialize(ttl)
+        raise ArgumentError, "ttl must be positive Float" unless ttl.is_a?(Float) && ttl.positive?
+
+        @elements = Concurrent::Map.new
+        @ttl      = ttl
+      end
+
+      # @param element [Object]
+      # @return [ExpirableSet] self
+      def add(element)
+        # cleanup expired elements to avoid mem-leak
+        horizon = now
+        expired = @elements.each_pair.select { |(_, sunset)| expired?(sunset, horizon) }
+        expired.each { |pair| @elements.delete_pair(*pair) }
+
+        # add new element
+        @elements[element] = now + @ttl
+
+        self
+      end
+
+      # @yield [Object] Gives each live (not expired) element to the block
+      def each
+        return to_enum __method__ unless block_given?
+
+        horizon = now
+
+        @elements.each_pair do |element, sunset|
+          yield element unless expired?(sunset, horizon)
+        end
+
+        self
+      end
+
+      private
+
+      # @return [Float]
+      def now
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+
+      def expired?(sunset, horizon)
+        sunset <= horizon
+      end
+    end
+  end
+end

data/lib/sidekiq/throttled/job.rb

@@ -13,7 +13,7 @@ module Sidekiq
     #       include Sidekiq::Job
     #       include Sidekiq::Throttled::Job
     #
-    #       sidkiq_options :queue => :my_queue
+    #       sidekiq_options :queue => :my_queue
     #       sidekiq_throttle :threshold => { :limit => 123, :period => 1.hour }
     #
     #       def perform
@@ -29,8 +29,8 @@ module Sidekiq
       #   in order to make API inline with `include Sidekiq::Job`.
       #
       # @private
-      def self.included(worker)
-        worker.send(:extend, ClassMethods)
+      def self.included(base)
+        base.extend(ClassMethods)
       end
 
       # Helper methods added to the singleton class of destination

data/lib/sidekiq/throttled/middleware.rb

@@ -9,14 +9,19 @@ module Sidekiq
     #
     # @private
     class Middleware
-      include Sidekiq::ServerMiddleware if Sidekiq::VERSION >= "6.5.0"
+      include Sidekiq::ServerMiddleware
 
       # Called within Sidekiq job processing
       def call(_worker, msg, _queue)
         yield
       ensure
-        Registry.get msg["class"] do |strategy|
-          strategy.finalize!(msg["jid"], *msg["args"])
+        job = msg.fetch("wrapped") { msg["class"] }
+        jid = msg["jid"]
+
+        if job && jid
+          Registry.get job do |strategy|
+            strategy.finalize!(jid, *msg["args"])
+          end
         end
       end
     end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+require "sidekiq/fetch"
+
+module Sidekiq
+  module Throttled
+    module Patches
+      module BasicFetch
+        # Retrieves job from redis.
+        #
+        # @return [Sidekiq::Throttled::UnitOfWork, nil]
+        def retrieve_work
+          work = super
+
+          if work && Throttled.throttled?(work.job)
+            Throttled.cooldown&.notify_throttled(work.queue)
+            requeue_throttled(work)
+            return nil
+          end
+
+          Throttled.cooldown&.notify_admitted(work.queue) if work
+
+          work
+        end
+
+        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.
+        # @param [Array<String>] queues
+        # @return [Array<String>]
+        def queues_cmd
+          super - (Throttled.cooldown&.queues || [])
+        end
+      end
+    end
+  end
+end
+
+Sidekiq::BasicFetch.prepend(Sidekiq::Throttled::Patches::BasicFetch)

data/lib/sidekiq/throttled/registry.rb

@@ -102,8 +102,6 @@ module Sidekiq
         # @param name [Class, #to_s]
         # @return [Strategy, nil]
         def find_by_class(name)
-          return unless Throttled.configuration.inherit_strategies?
-
           const = name.is_a?(Class) ? name : Object.const_get(name)
           return unless const.is_a?(Class)
 
@@ -112,6 +110,8 @@ module Sidekiq
             return strategy if strategy
           end
 
+          nil
+        rescue NameError
           nil
         end
       end

data/lib/sidekiq/throttled/strategy_collection.rb

@@ -19,8 +19,7 @@ module Sidekiq
       # @param [#to_s] name
       # @param [#call] key_suffix Dynamic key suffix generator.
       def initialize(strategies, strategy:, name:, key_suffix:)
-        strategies = (strategies.is_a?(Hash) ? [strategies] : Array(strategies))
-        @strategies = strategies.map do |options|
+        @strategies = (strategies.is_a?(Hash) ? [strategies] : Array(strategies)).map do |options|
           make_strategy(strategy, name, key_suffix, options)
         end
       end

data/lib/sidekiq/throttled/version.rb

@@ -3,6 +3,6 @@
 module Sidekiq
   module Throttled
     # Gem version
-    VERSION = "1.0.0.alpha"
+    VERSION = "1.0.0"
   end
 end

data/lib/sidekiq/throttled.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
-# 3rd party
 require "sidekiq"
 
-# internal
-require_relative "./throttled/version"
-require_relative "./throttled/configuration"
-require_relative "./throttled/fetch"
-require_relative "./throttled/registry"
+require_relative "./throttled/config"
+require_relative "./throttled/cooldown"
 require_relative "./throttled/job"
 require_relative "./throttled/middleware"
+require_relative "./throttled/patches/basic_fetch"
+require_relative "./throttled/registry"
+require_relative "./throttled/version"
 require_relative "./throttled/worker"
 
 # @see https://github.com/mperham/sidekiq/
@@ -42,21 +41,39 @@ module Sidekiq
   #       end
   #     end
   module Throttled
+    MUTEX = Mutex.new
+    private_constant :MUTEX
+
+    @config   = Config.new.freeze
+    @cooldown = Cooldown[@config]
+
     class << self
-      # @return [Configuration]
-      def configuration
-        @configuration ||= Configuration.new
-      end
+      # @api internal
+      #
+      # @return [Cooldown, nil]
+      attr_reader :cooldown
 
-      # Hooks throttler into sidekiq.
+      # @example
+      #   Sidekiq::Throttled.configure do |config|
+      #     config.cooldown_period = nil # Disable queues cooldown manager
+      #   end
       #
-      # @return [void]
+      # @yieldparam config [Config]
+      def configure
+        MUTEX.synchronize do
+          config = @config.dup
+
+          yield config
+
+          @config   = config.freeze
+          @cooldown = Cooldown[@config]
+        end
+      end
+
       def setup!
         Sidekiq.configure_server do |config|
-          if Gem::Version.new("7.0.0") <= Gem::Version.new(Sidekiq::VERSION)
-            config[:fetch_class] = Sidekiq::Throttled::Fetch
-          else
-            config[:fetch] = Sidekiq::Throttled::Fetch.new(config)
+          config.server_middleware do |chain|
+            chain.add Sidekiq::Throttled::Middleware
           end
         end
       end
@@ -66,11 +83,13 @@ module Sidekiq
       # @param [String] message Job's JSON payload
       # @return [Boolean]
       def throttled?(message)
-        message = JSON.parse message
-        job = message.fetch("wrapped") { message.fetch("class") { return false } }
-        jid = message.fetch("jid") { return false }
+        message = Sidekiq.load_json(message)
+        job     = message.fetch("wrapped") { message["class"] }
+        jid     = message["jid"]
 
-        Registry.get job do |strategy|
+        return false unless job && jid
+
+        Registry.get(job) do |strategy|
           return strategy.throttled?(jid, *message["args"])
         end
 
@@ -80,10 +99,4 @@ module Sidekiq
       end
     end
   end
-
-  configure_server do |config|
-    config.server_middleware do |chain|
-      chain.add Sidekiq::Throttled::Middleware
-    end
-  end
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-throttled
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha
+  version: 1.0.0
 platform: ruby
 authors:
 - Alexey Zapparov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-30 00:00:00.000000000 Z
+date: 2023-11-20 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: redis-prescription
   requirement: !ruby/object:Gem::Requirement
@@ -30,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '7.0'
 description:
 email:
 - alexey@zapparov.com
@@ -48,12 +62,13 @@ files:
 - LICENSE
 - README.adoc
 - lib/sidekiq/throttled.rb
-- lib/sidekiq/throttled/basic_fetch.rb
-- lib/sidekiq/throttled/configuration.rb
+- lib/sidekiq/throttled/config.rb
+- lib/sidekiq/throttled/cooldown.rb
 - lib/sidekiq/throttled/errors.rb
-- lib/sidekiq/throttled/fetch.rb
+- lib/sidekiq/throttled/expirable_set.rb
 - lib/sidekiq/throttled/job.rb
 - lib/sidekiq/throttled/middleware.rb
+- lib/sidekiq/throttled/patches/basic_fetch.rb
 - lib/sidekiq/throttled/registry.rb
 - lib/sidekiq/throttled/strategy.rb
 - lib/sidekiq/throttled/strategy/base.rb
@@ -72,9 +87,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ixti/sidekiq-throttled
-  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v1.0.0.alpha
+  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v1.0.0
   bug_tracker_uri: https://github.com/ixti/sidekiq-throttled/issues
-  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v1.0.0.alpha/CHANGES.md
+  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v1.0.0/CHANGES.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -84,12 +99,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.4.10
 signing_key:

data/lib/sidekiq/throttled/basic_fetch.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require "sidekiq"
-require "sidekiq/fetch"
-
-module Sidekiq
-  module Throttled
-    # Default Sidekiq's BasicFetch infused with Throttler.
-    #
-    # @private
-    class BasicFetch < Sidekiq::BasicFetch
-      # Retrieves job from redis.
-      #
-      # @return [Sidekiq::Throttled::UnitOfWork, nil]
-      def retrieve_work
-        work = super
-
-        if work && Throttled.throttled?(work.job)
-          requeue_throttled(work)
-          return nil
-        end
-
-        work
-      end
-
-      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.
-      # @param [Array<String>] queues
-      # @return [Array<String>]
-      def queues_cmd
-        queues = super
-
-        # TODO: Refactor to be prepended as an integration mixin during configuration stage
-        #   Or via configurable queues reducer
-        queues -= Sidekiq::Pauzer.paused_queues.map { |name| "queue:#{name}" } if defined?(Sidekiq::Pauzer)
-
-        queues
-      end
-    end
-  end
-end

data/lib/sidekiq/throttled/configuration.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-module Sidekiq
-  module Throttled
-    # Configuration holder.
-    class Configuration
-      # Class constructor.
-      def initialize
-        reset!
-      end
-
-      # Reset configuration to defaults.
-      #
-      # @return [self]
-      def reset!
-        @inherit_strategies = false
-
-        self
-      end
-
-      # Instructs throttler to lookup strategies in parent classes, if there's
-      # no own strategy:
-      #
-      #     class FooJob
-      #       include Sidekiq::Job
-      #       include Sidekiq::Throttled::Job
-      #
-      #       sidekiq_throttle :concurrency => { :limit => 42 }
-      #     end
-      #
-      #     class BarJob < FooJob
-      #     end
-      #
-      # By default in the example above, `Bar` won't have throttling options.
-      # Set this flag to `true` to enable this lookup in initializer, after
-      # that `Bar` will use `Foo` throttling bucket.
-      def inherit_strategies=(value)
-        @inherit_strategies = value ? true : false
-      end
-
-      # Whenever throttled workers should inherit parent's strategies or not.
-      # Default: `false`.
-      #
-      # @return [Boolean]
-      def inherit_strategies?
-        @inherit_strategies
-      end
-    end
-  end
-end

data/lib/sidekiq/throttled/fetch.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "./basic_fetch"
-
-module Sidekiq
-  module Throttled
-    # @deprecated Use Sidekiq::Throttled::BasicFetch
-    Fetch = BasicFetch
-  end
-end