redis-throttle 1.0.0 → 2.0.0

data/lib/redis_throttle.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require "concurrent/set"
+require "securerandom"
+
+require_relative "./redis_throttle/api"
+require_relative "./redis_throttle/concurrency"
+require_relative "./redis_throttle/rate_limit"
+require_relative "./redis_throttle/version"
+
+class RedisThrottle
+  class << self
+    # Syntax sugar for `RedisThrottle.new.concurrency(...)`.
+    #
+    # @see #concurrency
+    # @param (see #concurrency)
+    # @return (see #concurrency)
+    def concurrency(...)
+      new.concurrency(...)
+    end
+
+    # Syntax sugar for `RedisThrottle.new.rate_limit(...)`.
+    #
+    # @see #rate_limit
+    # @param (see #rate_limit)
+    # @return (see #rate_limit)
+    def rate_limit(...)
+      new.rate_limit(...)
+    end
+
+    # Return usage info for all known (in use) strategies.
+    #
+    # @example
+    #   RedisThrottle.info(:match => "*_api").each do |strategy, current_value|
+    #     # ...
+    #   end
+    #
+    # @param redis (see Api#initialize)
+    # @param match [#to_s]
+    # @return (see Api#info)
+    def info(redis, match: "*")
+      Api.new(redis).then { |api| api.info(strategies: api.strategies(match: match.to_s)) }
+    end
+  end
+
+  def initialize
+    @strategies = Concurrent::Set.new
+  end
+
+  # @api private
+  #
+  # Dup internal strategies plan.
+  #
+  # @return [void]
+  def initialize_dup(original)
+    super
+
+    @strategies = original.strategies.dup
+  end
+
+  # @api private
+  #
+  # Clone internal strategies plan.
+  #
+  # @return [void]
+  def initialize_clone(original)
+    super
+
+    @strategies = original.strategies.clone
+  end
+
+  # Add *concurrency* strategy to the throttle. Use it to guarantee `limit`
+  # amount of concurrently running code blocks.
+  #
+  # @example
+  #   throttle = RedisThrottle.new
+  #
+  #   # Allow max 2 concurrent execution units
+  #   throttle.concurrency(:xxx, limit: 2, ttl: 10)
+  #
+  #   throttle.acquire(redis, token: "a") && :aye || :nay # => :aye
+  #   throttle.acquire(redis, token: "b") && :aye || :nay # => :aye
+  #   throttle.acquire(redis, token: "c") && :aye || :nay # => :nay
+  #
+  #   throttle.release(redis, token: "a")
+  #
+  #   throttle.acquire(redis, token: "c") && :aye || :nay # => :aye
+  #
+  #
+  # @param (see Concurrency#initialize)
+  # @return [Throttle] self
+  def concurrency(bucket, limit:, ttl:)
+    raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+
+    @strategies << Concurrency.new(bucket, limit: limit, ttl: ttl)
+
+    self
+  end
+
+  # Add *rate limit* strategy to the throttle. Use it to guarantee `limit`
+  # amount of units in `period` of time.
+  #
+  # @example
+  #   throttle = RedisThrottle.new
+  #
+  #   # Allow 2 execution units per 10 seconds
+  #   throttle.rate_limit(:xxx, limit: 2, period: 10)
+  #
+  #   throttle.acquire(redis) && :aye || :nay # => :aye
+  #   sleep 5
+  #
+  #   throttle.acquire(redis) && :aye || :nay # => :aye
+  #   throttle.acquire(redis) && :aye || :nay # => :nay
+  #
+  #   sleep 6
+  #   throttle.acquire(redis) && :aye || :nay # => :aye
+  #   throttle.acquire(redis) && :aye || :nay # => :nay
+  #
+  # @param (see RateLimit#initialize)
+  # @return [Throttle] self
+  def rate_limit(bucket, limit:, period:)
+    raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+
+    @strategies << RateLimit.new(bucket, limit: limit, period: period)
+
+    self
+  end
+
+  # Merge in strategies of the `other` throttle.
+  #
+  # @example
+  #   a = RedisThrottle.concurrency(:a, limit: 1, ttl: 2)
+  #   b = RedisThrottle.rate_limit(:b, limit: 3, period: 4)
+  #   c = RedisThrottle
+  #     .concurrency(:a, limit: 1, ttl: 2)
+  #     .rate_limit(:b, limit: 3, period: 4)
+  #
+  #   a.merge!(b)
+  #
+  #   a == c # => true
+  #
+  # @return [Throttle] self
+  def merge!(other)
+    raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+
+    @strategies.merge(other.strategies)
+
+    self
+  end
+
+  # Non-destructive version of {#merge!}. Returns new {RedisThrottle} instance
+  # with union of `self` and `other` strategies.
+  #
+  # @example
+  #   a = RedisThrottle.concurrency(:a, limit: 1, ttl: 2)
+  #   b = RedisThrottle.rate_limit(:b, limit: 3, period: 4)
+  #   c = RedisThrottle
+  #     .concurrency(:a, limit: 1, ttl: 2)
+  #     .rate_limit(:b, limit: 3, period: 4)
+  #
+  #   a.merge(b) == c # => true
+  #   a == c          # => false
+  #
+  # @return [Throttle] new throttle
+  def merge(other)
+    dup.merge!(other)
+  end
+
+  alias + merge
+
+  # Prevents further modifications to the throttle instance.
+  #
+  # @see https://docs.ruby-lang.org/en/master/Object.html#method-i-freeze
+  # @return [Throttle] self
+  def freeze
+    @strategies.freeze
+
+    super
+  end
+
+  # Returns `true` if the `other` is an instance of {RedisThrottle} with
+  # the same set of strategies.
+  #
+  # @example
+  #   a = RedisThrottle
+  #     .concurrency(:a, limit: 1, ttl: 2)
+  #     .rate_limit(:b, limit: 3, period: 4)
+  #
+  #   b = RedisThrottle
+  #     .rate_limit(:b, limit: 3, period: 4)
+  #     .concurrency(:a, limit: 1, ttl: 2)
+  #
+  #   a == b # => true
+  #
+  # @return [Boolean]
+  def ==(other)
+    other.is_a?(self.class) && @strategies == other.strategies
+  end
+
+  alias eql? ==
+
+  # Calls given block execution lock was acquired, and ensures to {#release}
+  # it after the block.
+  #
+  # @example
+  #   throttle = RedisThrottle.concurrency(:xxx, limit: 1, ttl: 10)
+  #
+  #   throttle.call(redis) { :aye } # => :aye
+  #   throttle.call(redis) { :aye } # => :aye
+  #
+  #   throttle.acquire(redis)
+  #
+  #   throttle.call(redis) { :aye } # => nil
+  #
+  # @param redis (see Api#initialize)
+  # @param token (see #acquire)
+  # @return [Object] last satement of the block if execution lock was acquired.
+  # @return [nil] otherwise
+  def call(redis, token: SecureRandom.uuid)
+    return unless acquire(redis, token: token)
+
+    begin
+      yield
+    ensure
+      release(redis, token: token)
+    end
+  end
+
+  # Acquire execution lock.
+  #
+  # @example
+  #   throttle = RedisThrottle.concurrency(:xxx, limit: 1, ttl: 10)
+  #
+  #   if (token = throttle.acquire(redis))
+  #     # ... do something
+  #   end
+  #
+  #   throttle.release(redis, token: token) if token
+  #
+  # @see #call
+  # @see #release
+  # @param redis (see Api#initialize)
+  # @param token [#to_s] Unit of work ID
+  # @return [#to_s] `token` as is if lock was acquired
+  # @return [nil] otherwise
+  def acquire(redis, token: SecureRandom.uuid)
+    token if Api.new(redis).acquire(strategies: @strategies, token: token.to_s)
+  end
+
+  # Release acquired execution lock. Notice that this affects {#concurrency}
+  # locks only.
+  #
+  # @example
+  #   concurrency = RedisThrottle.concurrency(:xxx, limit: 1, ttl: 60)
+  #   rate_limit  = RedisThrottle.rate_limit(:xxx, limit: 1, period: 60)
+  #   throttle    = concurrency + rate_limit
+  #
+  #   throttle.acquire(redis, token: "uno")
+  #   throttle.release(redis, token: "uno")
+  #
+  #   concurrency.acquire(redis, token: "dos") # => "dos"
+  #   rate_limit.acquire(redis, token: "dos")  # => nil
+  #
+  # @see #acquire
+  # @see #reset
+  # @see #call
+  # @param redis (see Api#initialize)
+  # @param token [#to_s] Unit of work ID
+  # @return [void]
+  def release(redis, token:)
+    Api.new(redis).release(strategies: @strategies, token: token.to_s)
+
+    nil
+  end
+
+  # Flush all counters.
+  #
+  # @example
+  #   throttle = RedisThrottle.concurrency(:xxx, limit: 2, ttl: 60)
+  #
+  #   thottle.acquire(redis, token: "a") # => "a"
+  #   thottle.acquire(redis, token: "b") # => "b"
+  #   thottle.acquire(redis, token: "c") # => nil
+  #
+  #   throttle.reset(redis)
+  #
+  #   thottle.acquire(redis, token: "c") # => "c"
+  #   thottle.acquire(redis, token: "d") # => "d"
+  #
+  # @param redis (see Api#initialize)
+  # @return [void]
+  def reset(redis)
+    Api.new(redis).reset(strategies: @strategies)
+
+    nil
+  end
+
+  # Return usage info for all strategies of the throttle.
+  #
+  # @example
+  #   throttle.info(redis).each do |strategy, current_value|
+  #     # ...
+  #   end
+  #
+  # @param redis (see Api#initialize)
+  # @return (see Api#info)
+  def info(redis)
+    Api.new(redis).info(strategies: @strategies)
+  end
+
+  protected
+
+  attr_accessor :strategies
+end

metadata

@@ -1,44 +1,44 @@
 --- !ruby/object:Gem::Specification
 name: redis-throttle
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Alexey Zapparov
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-14 00:00:00.000000000 Z
+date: 2023-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: redis
+  name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 1.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: redis-prescription
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '2.5'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: 
+        version: '2.5'
+description:
 email:
 - alexey@zapparov.com
 executables: []
@@ -46,40 +46,40 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
-- lib/redis/throttle.rb
-- lib/redis/throttle/api.lua
-- lib/redis/throttle/api.rb
-- lib/redis/throttle/class_methods.rb
-- lib/redis/throttle/concurrency.rb
-- lib/redis/throttle/errors.rb
-- lib/redis/throttle/rate_limit.rb
-- lib/redis/throttle/script.rb
-- lib/redis/throttle/version.rb
+- README.adoc
+- lib/redis-throttle.rb
+- lib/redis_throttle.rb
+- lib/redis_throttle/api.lua
+- lib/redis_throttle/api.rb
+- lib/redis_throttle/concurrency.rb
+- lib/redis_throttle/rate_limit.rb
+- lib/redis_throttle/version.rb
 homepage: https://gitlab.com/ixti/redis-throttle
 licenses:
 - MIT
 metadata:
   homepage_uri: https://gitlab.com/ixti/redis-throttle
-  source_code_uri: https://gitlab.com/ixti/redis-throttle/tree/v1.0.0
+  source_code_uri: https://gitlab.com/ixti/redis-throttle/tree/v2.0.0
   bug_tracker_uri: https://gitlab.com/ixti/redis-throttle/issues
-  changelog_uri: https://gitlab.com/ixti/redis-throttle/blob/v1.0.0/CHANGES.md
-post_install_message: 
+  changelog_uri: https://gitlab.com/ixti/redis-throttle/blob/v2.0.0/CHANGES.md
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.33
+signing_key:
 specification_version: 4
-summary: Redis based rate limit and concurrency throttling.
+summary: Redis based rate limit and concurrency throttling
 test_files: []

data/lib/redis/throttle/api.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-require "redis"
-
-require_relative "./script"
-require_relative "./concurrency"
-require_relative "./rate_limit"
-
-class Redis
-  class Throttle
-    # @api private
-    class Api
-      NAMESPACE = "throttle"
-      private_constant :NAMESPACE
-
-      KEYS_PATTERN = %r{
-        \A
-        #{NAMESPACE}:
-        (?<strategy>concurrency|rate_limit):
-        (?<bucket>.+):
-        (?<limit>\d+):
-        (?<ttl_or_period>\d+)
-        \z
-      }x.freeze
-      private_constant :KEYS_PATTERN
-
-      SCRIPT = Script.new(File.read("#{__dir__}/api.lua"))
-      private_constant :SCRIPT
-
-      # @param redis [Redis, Redis::Namespace, #to_proc]
-      def initialize(redis: nil)
-        @redis =
-          if redis.respond_to?(:to_proc)
-            redis.to_proc
-          else
-            ->(&b) { b.call(redis || Redis.current) }
-          end
-      end
-
-      # @param strategies [Enumerable<Concurrency, RateLimit>]
-      # @param token [String]
-      # @return [Boolean]
-      def acquire(strategies:, token:)
-        execute(:ACQUIRE, to_params(strategies) << :TOKEN << token << :TS << Time.now.to_i).zero?
-      end
-
-      # @param strategies [Enumerable<Concurrency, RateLimit>]
-      # @param token [String]
-      # @return [void]
-      def release(strategies:, token:)
-        execute(:RELEASE, to_params(strategies.grep(Concurrency)) << :TOKEN << token)
-      end
-
-      # @param strategies [Enumerable<Concurrency, RateLimit>]
-      # @return [void]
-      def reset(strategies:)
-        execute(:RESET, to_params(strategies))
-      end
-
-      # @param match [String]
-      # @return [Array<Concurrency, RateLimit>]
-      def strategies(match:)
-        results = []
-
-        @redis.call do |redis|
-          redis.scan_each(:match => "#{NAMESPACE}:*:#{match}:*:*") do |key|
-            strategy = from_key(key)
-            results << strategy if strategy
-          end
-        end
-
-        results
-      end
-
-      # @param strategies [Enumerable<Concurrency, RateLimit>]
-      # @return [Hash{Concurrency => Integer, RateLimit => Integer}]
-      def info(strategies:)
-        strategies.zip(execute(:INFO, to_params(strategies) << :TS << Time.now.to_i)).to_h
-      end
-
-      # @note Used for specs only.
-      # @return [void]
-      def ping
-        @redis.call(&:ping)
-      end
-
-      private
-
-      def execute(command, argv)
-        @redis.call { |redis| SCRIPT.call(redis, :keys => [NAMESPACE], :argv => [command, *argv]) }
-      end
-
-      def from_key(key)
-        md = KEYS_PATTERN.match(key)
-
-        case md && md[:strategy]
-        when "concurrency"
-          Concurrency.new(md[:bucket], :limit => md[:limit], :ttl => md[:ttl_or_period])
-        when "rate_limit"
-          RateLimit.new(md[:bucket], :limit => md[:limit], :period => md[:ttl_or_period])
-        end
-      end
-
-      def to_params(strategies)
-        result = []
-
-        strategies.each do |strategy|
-          case strategy
-          when Concurrency
-            result << "concurrency" << strategy.bucket << strategy.limit << strategy.ttl
-          when RateLimit
-            result << "rate_limit" << strategy.bucket << strategy.limit << strategy.period
-          end
-        end
-
-        result
-      end
-    end
-  end
-end

data/lib/redis/throttle/class_methods.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "./api"
-
-class Redis
-  class Throttle
-    module ClassMethods
-      # Syntax sugar for {Throttle#concurrency}.
-      #
-      # @see #concurrency
-      # @param (see Throttle#initialize)
-      # @param (see Throttle#concurrency)
-      # @return (see Throttle#concurrency)
-      def concurrency(bucket, limit:, ttl:, redis: nil)
-        new(:redis => redis).concurrency(bucket, :limit => limit, :ttl => ttl)
-      end
-
-      # Syntax sugar for {Throttle#rate_limit}.
-      #
-      # @see #concurrency
-      # @param (see Throttle#initialize)
-      # @param (see Throttle#rate_limit)
-      # @return (see Throttle#rate_limit)
-      def rate_limit(bucket, limit:, period:, redis: nil)
-        new(:redis => redis).rate_limit(bucket, :limit => limit, :period => period)
-      end
-
-      # Return usage info for all known (in use) strategies.
-      #
-      # @example
-      #   Redis::Throttle.info(:match => "*_api").each do |strategy, current_value|
-      #     # ...
-      #   end
-      #
-      # @param match [#to_s]
-      # @return (see Api#info)
-      def info(match: "*", redis: nil)
-        api        = Api.new(:redis => redis)
-        strategies = api.strategies(:match => match.to_s)
-
-        api.info(:strategies => strategies)
-      end
-    end
-  end
-end

data/lib/redis/throttle/concurrency.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-class Redis
-  class Throttle
-    class Concurrency
-      # @!attribute [r] bucket
-      #   @return [String] Throttling group name
-      attr_reader :bucket
-
-      # @!attribute [r] limit
-      #   @return [Integer] Max allowed concurrent units
-      attr_reader :limit
-
-      # @!attribute [r] ttl
-      #   @return [Integer] Time (in seconds) to hold the lock before
-      #     releasing it (in case it wasn't released already)
-      attr_reader :ttl
-
-      # @param bucket [#to_s] Throttling group name
-      # @param limit [#to_i] Max allowed concurrent units
-      # @param ttl [#to_i] Time (in seconds) to hold the lock before
-      #   releasing it (in case it wasn't released already)
-      def initialize(bucket, limit:, ttl:)
-        @bucket = -bucket.to_s
-        @limit  = limit.to_i
-        @ttl    = ttl.to_i
-      end
-
-      # Returns `true` if `other` is a {Concurrency} instance with the same
-      # {#bucket}, {#limit}, and {#ttl}.
-      #
-      # @see https://docs.ruby-lang.org/en/master/Object.html#method-i-eql-3F
-      # @param other [Object]
-      # @return [Boolean]
-      def ==(other)
-        return true  if equal? other
-        return false unless other.is_a?(self.class)
-
-        @bucket == other.bucket && @limit == other.limit && @ttl == other.ttl
-      end
-
-      alias eql? ==
-
-      # @api private
-      #
-      # Compare `self` with `other` strategy:
-      #
-      # - Returns `nil` if `other` is neither {Concurrency} nor {RateLimit}
-      # - Returns `1` if `other` is a {RateLimit}
-      # - Returns `1` if `other` is a {Concurrency} with lower {#limit}
-      # - Returns `0` if `other` is a {Concurrency} with the same {#limit}
-      # - Returns `-1` if `other` is a {Concurrency} with bigger {#limit}
-      #
-      # @return [-1, 0, 1, nil]
-      def <=>(other)
-        complexity <=> other.complexity if other.respond_to? :complexity
-      end
-
-      # @api private
-      #
-      # Generates an Integer hash value for this object.
-      #
-      # @see https://docs.ruby-lang.org/en/master/Object.html#method-i-hash
-      # @return [Integer]
-      def hash
-        @hash ||= [@bucket, @limit, @ttl].hash
-      end
-
-      # @api private
-      #
-      # @return [Array(Integer, Integer)] Strategy complexity pseudo-score
-      def complexity
-        [1, @limit]
-      end
-    end
-  end
-end

data/lib/redis/throttle/errors.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-class Redis
-  class Throttle
-    class Error < StandardError; end
-    class ScriptError < Error; end
-
-    class FrozenError < RuntimeError; end if RUBY_VERSION < "2.5"
-  end
-end