redis-throttle 1.0.0 → 1.1.0

data/lib/redis_throttle/concurrency.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+class RedisThrottle
+  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

data/lib/redis_throttle/rate_limit.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+class RedisThrottle
+  class RateLimit
+    # @!attribute [r] bucket
+    #   @return [String] Throttling group name
+    attr_reader :bucket
+
+    # @!attribute [r] limit
+    #   @return [Integer] Max allowed units per {#period}
+    attr_reader :limit
+
+    # @!attribute [r] period
+    #   @return [Integer] Period in seconds
+    attr_reader :period
+
+    # @param bucket [#to_s] Throttling group name
+    # @param limit [#to_i] Max allowed units per `period`
+    # @param period [#to_i] Period in seconds
+    def initialize(bucket, limit:, period:)
+      @bucket = -bucket.to_s
+      @limit  = limit.to_i
+      @period = period.to_i
+    end
+
+    # Returns `true` if `other` is a {RateLimit} instance with the same
+    # {#bucket}, {#limit}, and {#period}.
+    #
+    # @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 && @period == other.period
+    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 {Concurrency}
+    # - Returns `1` if `other` is a {RateLimit} with lower {#limit}
+    # - Returns `0` if `other` is a {RateLimit} with the same {#limit}
+    # - Returns `-1` if `other` is a {RateLimit} 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, @period].hash
+    end
+
+    # @api private
+    #
+    # @return [Array(Integer, Integer)] Strategy complexity pseudo-score
+    def complexity
+      [0, @limit]
+    end
+  end
+end

data/lib/redis_throttle/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class RedisThrottle
+  # Gem version.
+  VERSION = "1.1.0"
+end

data/lib/redis_throttle.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "concurrent/set"
+require "securerandom"
+
+require_relative "./redis_throttle/api"
+require_relative "./redis_throttle/class_methods"
+require_relative "./redis_throttle/concurrency"
+require_relative "./redis_throttle/rate_limit"
+require_relative "./redis_throttle/version"
+
+class RedisThrottle
+  extend ClassMethods
+
+  # @param (see Api#initialize)
+  def initialize(redis: nil)
+    # TODO: fix api cloning/duping
+    @api        = Api.new(redis: redis)
+    @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(:token => "a") && :aye || :nay # => :aye
+  #   throttle.acquire(:token => "b") && :aye || :nay # => :aye
+  #   throttle.acquire(:token => "c") && :aye || :nay # => :nay
+  #
+  #   throttle.release(:token => "a")
+  #
+  #   throttle.acquire(: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 && :aye || :nay # => :aye
+  #   sleep 5
+  #
+  #   throttle.acquire && :aye || :nay # => :aye
+  #   throttle.acquire && :aye || :nay # => :nay
+  #
+  #   sleep 6
+  #   throttle.acquire && :aye || :nay # => :aye
+  #   throttle.acquire && :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
+
+  alias << merge!
+
+  # Non-destructive version of {#merge!}. Returns new {Throttle} 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
+
+  # @deprecated will be removed in 2.0.0
+  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 {Throttle} 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 { :aye } # => :aye
+  #   throttle.call { :aye } # => :aye
+  #
+  #   throttle.acquire
+  #
+  #   throttle.call { :aye } # => nil
+  #
+  # @param (see #acquire)
+  # @return [Object] last satement of the block if execution lock was acquired.
+  # @return [nil] otherwise
+  def call(token: SecureRandom.uuid)
+    return unless acquire(token: token)
+
+    begin
+      yield
+    ensure
+      release(token: token)
+    end
+  end
+
+  # Acquire execution lock.
+  #
+  # @example
+  #   throttle = RedisThrottle.concurrency(:xxx, :limit => 1, :ttl => 10)
+  #
+  #   if (token = throttle.acquire)
+  #     # ... do something
+  #   end
+  #
+  #   throttle.release(:token => token) if token
+  #
+  # @see #call
+  # @see #release
+  # @param token [#to_s] Unit of work ID
+  # @return [#to_s] `token` as is if lock was acquired
+  # @return [nil] otherwise
+  def acquire(token: SecureRandom.uuid)
+    token if @api.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(:token => "uno")
+  #   throttle.release(:token => "uno")
+  #
+  #   concurrency.acquire(:token => "dos") # => "dos"
+  #   rate_limit.acquire(:token => "dos")  # => nil
+  #
+  # @see #acquire
+  # @see #reset
+  # @see #call
+  # @param token [#to_s] Unit of work ID
+  # @return [void]
+  def release(token:)
+    @api.release(strategies: @strategies, token: token.to_s)
+
+    nil
+  end
+
+  # Flush all counters.
+  #
+  # @example
+  #   throttle = RedisThrottle.concurrency(:xxx, :limit => 2, :ttl => 60)
+  #
+  #   thottle.acquire(:token => "a") # => "a"
+  #   thottle.acquire(:token => "b") # => "b"
+  #   thottle.acquire(:token => "c") # => nil
+  #
+  #   throttle.reset
+  #
+  #   thottle.acquire(:token => "c") # => "c"
+  #   thottle.acquire(:token => "d") # => "d"
+  #
+  # @return [void]
+  def reset
+    @api.reset(strategies: @strategies)
+
+    nil
+  end
+
+  # Return usage info for all strategies of the throttle.
+  #
+  # @example
+  #   throttle.info.each do |strategy, current_value|
+  #     # ...
+  #   end
+  #
+  # @return (see Api#info)
+  def info
+    @api.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: 1.1.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.2.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description: 
+        version: 2.2.0
+description:
 email:
 - alexey@zapparov.com
 executables: []
@@ -46,40 +46,42 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
+- README.adoc
+- lib/redis-throttle.rb
 - 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
+- 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/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/v1.1.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/v1.1.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.3.26
+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