sidekiq-throttled 0.11.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '05945dcd1de433dd74010e8fa402c6fb2e6100fb6306aef386536da24cd2e08b'
-  data.tar.gz: fe07b3c6409e7749f2af3b85d36e27dcda5d53b92c771e050a951f6175cec407
+  metadata.gz: c7e45d38e16a4fd149ab2a5df541308d54304ae35bbd337d3701e534bffa025b
+  data.tar.gz: 7aa8a7a9469dbec0d06df4829dee111f015119861ac0caff00ca70148d014602
 SHA512:
-  metadata.gz: 2965642d0564eaf45c033b6c6d6ddfe5b80804eebfbfef7908c4f81bbc450baec4e71d1b70fe21bf6515336d173b3a95e74c4b97aa26d35a3947b7b24ba02c1e
-  data.tar.gz: 149ba3f6d29c9963c52f96d7ea1b6be23424726a7791afe7c3fad4ab95bf82b2db0df274ee3a26842e7726e1f403afff2d99c997f1033f2ddb63a95f9790d698
+  metadata.gz: 29e1a58bf302daeacb18695a618e55eec6ec177112274ac5dc85f7fbc1b14cb56c1bb8f8e9250dd22683182c8baee0d95c40f3708dba8518a5dde7cfbc71bbb6
+  data.tar.gz: 24ada7f5c9ee65400d1442feb72f95428ef9efdaf7aac2d38b732b2f4d649709712fb25d6b97e2c59627647bdcadf4c5d206fbb46f9b8321a5d293184866f2d2

data/{LICENSE.md → LICENSE}

@@ -1,6 +1,8 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2018 SensorTower Inc.
+Copyright (c) 2022 Alexey Zapparov
+Copyright (c) 2020-2021 Alexey Zapparov, SensorTower Inc.
+Copyright (c) 2015-2020 SensorTower Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.adoc

@@ -0,0 +1,296 @@
+= Sidekiq::Throttled
+:ci-link: https://github.com/ixti/sidekiq-throttled/actions/workflows/ci.yml
+:ci-badge: https://img.shields.io/github/actions/workflow/status/ixti/sidekiq-throttled/ci.yml?branch=main&style=for-the-badge
+:gem-link: http://rubygems.org/gems/sidekiq-throttled
+:gem-badge: https://img.shields.io/gem/v/sidekiq-throttled?style=for-the-badge
+:doc-link: http://www.rubydoc.info/gems/sidekiq-throttled
+:doc-badge: https://img.shields.io/badge/Documentation-API-blue?style=for-the-badge
+
+****
+{ci-link}[image:{ci-badge}[CI Status]]
+{gem-link}[image:{gem-badge}[Latest Version]]
+{doc-link}[image:{doc-badge}[API Documentation]]
+****
+
+NOTE: This is the 1.x *development* branch. For the 0.x *stable* branch, please
+  see: https://github.com/ixti/sidekiq-throttled/tree/0-x-stable[0-x-stable]
+
+Concurrency and threshold throttling for https://github.com/mperham/sidekiq[Sidekiq].
+
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem "sidekiq-throttled"
+----
+
+And then execute:
+
+  $ bundle
+
+Or install it yourself as:
+
+  $ gem install sidekiq-throttled
+
+
+== Usage
+
+Add somewhere in your app's bootstrap (e.g. `config/initializers/sidekiq.rb` if
+you are using Rails):
+
+[source,ruby]
+----
+require "sidekiq/throttled"
+Sidekiq::Throttled.setup!
+----
+
+Load order can be an issue if you are using other Sidekiq plugins and/or middleware.
+To prevent any problems, add the `.setup!` call to the bottom of your init file.
+
+Once you've done that you can include `Sidekiq::Throttled::Job` to your
+job classes and configure throttling:
+
+[source,ruby]
+----
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Throttled::Job
+
+  sidekiq_options :queue => :my_queue
+
+  sidekiq_throttle(
+    # Allow maximum 10 concurrent jobs of this class at a time.
+    concurrency: { limit: 10 },
+    # Allow maximum 1K jobs being processed within one hour window.
+    threshold: { limit: 1_000, period: 1.hour }
+  )
+
+  def perform
+    # ...
+  end
+end
+----
+
+TIP: `Sidekiq::Throttled::Job` is aliased as `Sidekiq::Throttled::Worker`,
+  thus if you're using `Sidekiq::Worker` naming convention, you can use the
+  alias for consistency:
+
+[source,ruby]
+----
+class MyWorker
+  include Sidekiq::Worker
+  include Sidekiq::Throttled::Worker
+
+  # ...
+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
+`:observer` option with callable object:
+
+[source,ruby]
+----
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Throttled::Job
+
+  MY_OBSERVER = lambda do |strategy, *args|
+    # do something
+  end
+
+  sidekiq_options queue: :my_queue
+
+  sidekiq_throttle(
+    concurrency: { limit: 10 },
+    threshold:   { limit: 100, period: 1.hour },
+    observer:    MY_OBSERVER
+  )
+
+  def perform(*args)
+    # ...
+  end
+end
+----
+
+Observer will receive `strategy, *args` arguments, where `strategy` is a Symbol
+`:concurrency` or `:threshold`, and `*args` are the arguments that were passed
+to the job.
+
+
+=== Dynamic throttling
+
+You can throttle jobs dynamically with `:key_suffix` option:
+
+[source,ruby]
+----
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Throttled::Job
+
+  sidekiq_options queue: :my_queue
+
+  sidekiq_throttle(
+    # Allow maximum 10 concurrent jobs per user at a time.
+    concurrency: { limit: 10, key_suffix: -> (user_id) { user_id } }
+  )
+
+  def perform(user_id)
+    # ...
+  end
+end
+----
+
+You can also supply dynamic values for limits and periods by supplying a proc
+for these values. The proc will be evaluated at the time the job is fetched
+and will receive the same arguments that are passed to the job.
+
+[source,ruby]
+----
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Throttled::Job
+
+  sidekiq_options queue: :my_queue
+
+  sidekiq_throttle(
+    # Allow maximum 1000 concurrent jobs of this class at a time for VIPs and 10 for all other users.
+    concurrency: {
+      limit:      ->(user_id) { User.vip?(user_id) ? 1_000 : 10 },
+      key_suffix: ->(user_id) { User.vip?(user_id) ? "vip" : "std" }
+    },
+    # Allow 1000 jobs/hour to be processed for VIPs and 10/day for all others
+    threshold: {
+      limit:      ->(user_id) { User.vip?(user_id) ? 1_000 : 10 },
+      period:     ->(user_id) { User.vip?(user_id) ? 1.hour : 1.day },
+      key_suffix: ->(user_id) { User.vip?(user_id) ? "vip" : "std" }
+    }
+  )
+
+  def perform(user_id)
+    # ...
+  end
+end
+----
+
+You also can use several different keys to throttle one worker.
+
+[source,ruby]
+----
+class MyJob
+  include Sidekiq::Job
+  include Sidekiq::Throttled::Job
+
+  sidekiq_options queue: :my_queue
+
+  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 } }
+    ]
+    # For :threshold it works the same
+  )
+
+  def perform(project_id, user_id)
+    # ...
+  end
+end
+----
+
+IMPORTANT: Don't forget to specify `:key_suffix` and make it return different
+  values if you are using dynamic limit/period options. Otherwise, you risk
+  getting into some trouble.
+
+
+=== Concurrency throttling fine-tuning
+
+Concurrency throttling is based on distributed locks. Those locks have default
+time to live (TTL) set to 15 minutes. If your job takes more than 15 minutes
+to finish, lock will be released and you might end up with more jobs running
+concurrently than you expect.
+
+This is done to avoid deadlocks - when by any reason (e.g. Sidekiq process was
+OOM-killed) cleanup middleware wasn't executed and locks were not released.
+
+If your job takes more than 15 minutes to complete, you can tune concurrency
+lock TTL to fit your needs:
+
+[source,ruby]
+----
+# Set concurrency strategy lock TTL to 1 hour.
+sidekiq_throttle(concurrency: { limit: 20, ttl: 1.hour.to_i })
+----
+
+
+== Supported Ruby Versions
+
+This library aims to support and is tested against the following Ruby versions:
+
+* Ruby 3.0.x
+* Ruby 3.1.x
+* Ruby 3.2.x
+
+If something doesn't work on one of these versions, it's a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby versions,
+however support will only be provided for the versions listed above.
+
+If you would like this library to support another Ruby version or
+implementation, you may volunteer to be a maintainer. Being a maintainer
+entails making sure all tests run and pass on that implementation. When
+something breaks on your implementation, you will be responsible for providing
+patches in a timely fashion. If critical issues for a particular implementation
+exist at the time of a major release, support for that Ruby version may be
+dropped.
+
+
+== Supported Sidekiq Versions
+
+This library aims to support and work with following Sidekiq versions:
+
+* Sidekiq 7.0.x
+* Sidekiq 7.1.x
+* Sidekiq 7.2.x
+
+
+== Development
+
+  bundle install
+  bundle exec appraisal generate
+  bundle exec appraisal install
+  bundle exec rake
+
+
+== Contributing
+
+* Fork sidekiq-throttled on GitHub
+* Make your changes
+* Ensure all tests pass (`bundle exec rake`)
+* Send a pull request
+* If we like them we'll merge them
+* If we've accepted a patch, feel free to ask for commit access!

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# internal
+require_relative "./registry"
+
+module Sidekiq
+  module Throttled
+    # Adds helpers to your worker classes
+    #
+    # @example Usage
+    #
+    #     class MyJob
+    #       include Sidekiq::Job
+    #       include Sidekiq::Throttled::Job
+    #
+    #       sidekiq_options :queue => :my_queue
+    #       sidekiq_throttle :threshold => { :limit => 123, :period => 1.hour }
+    #
+    #       def perform
+    #         # ...
+    #       end
+    #     end
+    #
+    # @see ClassMethods
+    module Job
+      # Extends worker class with {ClassMethods}.
+      #
+      # @note Using `included` hook with extending worker with {ClassMethods}
+      #   in order to make API inline with `include Sidekiq::Job`.
+      #
+      # @private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Helper methods added to the singleton class of destination
+      module ClassMethods
+        # Registers some strategy for the worker.
+        #
+        # @example Allow max 123 MyJob jobs per hour
+        #
+        #     class MyJob
+        #       include Sidekiq::Job
+        #       include Sidekiq::Throttled::Job
+        #
+        #       sidekiq_throttle({
+        #         :threshold => { :limit => 123, :period => 1.hour }
+        #       })
+        #     end
+        #
+        # @example Allow max 10 concurrently running MyJob jobs
+        #
+        #     class MyJob
+        #       include Sidekiq::Job
+        #       include Sidekiq::Throttled::Job
+        #
+        #       sidekiq_throttle({
+        #         :concurrency => { :limit => 10 }
+        #       })
+        #     end
+        #
+        # @example Allow max 10 concurrent MyJob jobs and max 123 per hour
+        #
+        #     class MyJob
+        #       include Sidekiq::Job
+        #       include Sidekiq::Throttled::Job
+        #
+        #       sidekiq_throttle({
+        #         :threshold => { :limit => 123, :period => 1.hour },
+        #         :concurrency => { :limit => 10 }
+        #       })
+        #     end
+        #
+        # @see Registry.add
+        # @return [void]
+        def sidekiq_throttle(**kwargs)
+          Registry.add(self, **kwargs)
+        end
+
+        # Adds current worker to preconfigured throttling strategy. Allows
+        # sharing same pool for multiple workers.
+        #
+        # First of all we need to create shared throttling strategy:
+        #
+        #     # Create google_api throttling strategy
+        #     Sidekiq::Throttled::Registry.add(:google_api, {
+        #       :threshold => { :limit => 123, :period => 1.hour },
+        #       :concurrency => { :limit => 10 }
+        #     })
+        #
+        # Now we can assign it to our workers:
+        #
+        #     class FetchProfileJob
+        #       include Sidekiq::Job
+        #       include Sidekiq::Throttled::Job
+        #
+        #       sidekiq_throttle_as :google_api
+        #     end
+        #
+        #     class FetchCommentsJob
+        #       include Sidekiq::Job
+        #       include Sidekiq::Throttled::Job
+        #
+        #       sidekiq_throttle_as :google_api
+        #     end
+        #
+        # With the above configuration we ensure that there are maximum 10
+        # concurrently running jobs of FetchProfileJob or FetchCommentsJob
+        # allowed. And only 123 jobs of those are executed per hour.
+        #
+        # In other words, it will allow:
+        #
+        # - only `X` concurrent `FetchProfileJob`s
+        # - max `XX` `FetchProfileJob` per hour
+        # - only `Y` concurrent `FetchCommentsJob`s
+        # - max `YY` `FetchCommentsJob` per hour
+        #
+        # Where `(X + Y) == 10` and `(XX + YY) == 123`
+        #
+        # @see Registry.add_alias
+        # @return [void]
+        def sidekiq_throttle_as(name)
+          Registry.add_alias(self, name)
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/throttled/middleware.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # internal
-require "sidekiq/throttled/registry"
+require_relative "./registry"
 
 module Sidekiq
   module Throttled
@@ -9,12 +9,19 @@ module Sidekiq
     #
     # @private
     class Middleware
+      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)