redis-throttle 1.0.0 → 2.0.0

data/lib/redis/throttle/rate_limit.rb

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

data/lib/redis/throttle/script.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-require "redis/errors"
-
-require_relative "./errors"
-
-class Redis
-  class Throttle
-    # @api private
-    #
-    # Lazy-compile and run acquire script by it's sha1 digest.
-    class Script
-      # Redis error fired when script ID is unkown.
-      NOSCRIPT = "NOSCRIPT"
-      private_constant :NOSCRIPT
-
-      LUA_ERROR_MESSAGE = %r{
-        ERR\s
-        (?<message>Error\s(?:compiling|running)\sscript)
-        \s\([^()]+\):\s
-        (?:@[^:]+:\d+:\s)?
-        [^:]+:(?<loc>\d+):\s
-        (?<details>.+)
-      }x.freeze
-      private_constant :LUA_ERROR_MESSAGE
-
-      def initialize(source)
-        @source = -source.to_s
-        @digest = Digest::SHA1.hexdigest(@source).freeze
-      end
-
-      def call(redis, keys: [], argv: [])
-        __eval__(redis, keys, argv)
-      rescue Redis::CommandError => e
-        md = LUA_ERROR_MESSAGE.match(e.message.to_s)
-        raise unless md
-
-        raise ScriptError, "#{md[:message]} @#{md[:loc]}: #{md[:details]}"
-      end
-
-      private
-
-      def __eval__(redis, keys, argv)
-        redis.evalsha(@digest, keys, argv)
-      rescue Redis::CommandError => e
-        raise unless e.message.include?(NOSCRIPT)
-
-        redis.eval(@source, keys, argv)
-      end
-    end
-  end
-end

data/lib/redis/throttle/version.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-class Redis
-  class Throttle
-    # Gem version.
-    VERSION = "1.0.0"
-  end
-end

data/lib/redis/throttle.rb

@@ -1,288 +0,0 @@
-# frozen_string_literal: true
-
-require "redis"
-require "set"
-require "securerandom"
-
-require_relative "./throttle/api"
-require_relative "./throttle/errors"
-require_relative "./throttle/class_methods"
-require_relative "./throttle/concurrency"
-require_relative "./throttle/rate_limit"
-require_relative "./throttle/version"
-
-# @see https://github.com/redis/redis-rb
-class Redis
-  # Distributed rate limit and concurrency throttling.
-  class Throttle
-    extend ClassMethods
-
-    # @param (see Api#initialize)
-    def initialize(redis: nil)
-      @api        = Api.new(:redis => redis)
-      @strategies = SortedSet.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 = Redis::Throttle.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 = Redis::Throttle.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 = Redis::Throttle.concurrency(:a, :limit => 1, :ttl => 2)
-    #   b = Redis::Throttle.rate_limit(:b, :limit => 3, :period => 4)
-    #   c = Redis::Throttle
-    #     .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 = Redis::Throttle.concurrency(:a, :limit => 1, :ttl => 2)
-    #   b = Redis::Throttle.rate_limit(:b, :limit => 3, :period => 4)
-    #   c = Redis::Throttle
-    #     .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 {Throttle} with the same
-    # set of strategies.
-    #
-    # @example
-    #   a = Redis::Throttle
-    #     .concurrency(:a, :limit => 1, :ttl => 2)
-    #     .rate_limit(:b, :limit => 3, :period => 4)
-    #
-    #   b = Redis::Throttle
-    #     .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 = Redis::Throttle.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 = Redis::Throttle.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 = Redis::Throttle.concurrency(:xxx, :limit => 1, :ttl => 60)
-    #   rate_limit  = Redis::Throttle.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 = Redis::Throttle.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
-end