redis-throttle 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6578fcf4ed5b682873d8f6c31a629bf8ab04fa3f747a6e85e67d552fa22ad40
-  data.tar.gz: c3d2ea3307187912af4d4f93ecee4f8a2fc2e386922511b63e3a9ad93e547c49
+  metadata.gz: 94cbed31445714a0f2883bfbe8e317dff6813db80d93c73b7a16a32dfb45524a
+  data.tar.gz: 5aa8ecb1c5d5301f314f844bbdbdd720d26d881b6820966cf42682302bd00178
 SHA512:
-  metadata.gz: 861efde66ca39700db8a6922add9e7539ecd13b9ecea1a79fe14575df1ca75772ac49608a298bbdb92fce7ec7681cb40eeaf3768089e7481395c57eb6ad23418
-  data.tar.gz: a1299fb9d99b21c5cca90823812e77feda7fccc7ed4e69778afcd2bb87a0c74aa94f48746047f3fd8b02ccf2076d4344c4047ca499b69090bfffd823cdc6ae87
+  metadata.gz: 89d197efa9dadad39539510da10ec183c2df3f00c1b12063591827ab7ffd02b368ab92a9643a20d83dc40751bbfa2cdf33ae42f2d41717d314d40f496628af53
+  data.tar.gz: d07140bc01e01b051dcabd266b0a2d5410ce9289d74b5550c44da903c8d3b0f5e574a8cef3ae5b777b26fb1d5557e2fb294e9b0a7394b75e77c0c31e047def75

data/lib/redis/throttle.rb

@@ -1,12 +1,288 @@
 # frozen_string_literal: true
 
-require_relative "throttle/errors"
-require_relative "throttle/version"
-require_relative "throttle/concurrency"
-require_relative "throttle/threshold"
+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 threshold and concurrency throttling.
-  module Throttle; end
+  # 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

data/lib/redis/throttle/api.lua

@@ -0,0 +1,195 @@
+if 1 ~= #KEYS or 0 == #ARGV then
+  return redis.error_reply("syntax error")
+end
+
+local commands = {}
+
+commands.ACQUIRE = {
+  params = { "strategies", "token", "timestamp" },
+  handler = function (params)
+    local now   = params.timestamp
+    local token = params.token
+    local locks = {}
+
+    local acquire = {
+      rate_limit = function (strategy)
+        local key, limit, period = strategy.key, strategy.limit, strategy.period
+
+        if redis.call("LLEN", key) < limit or tonumber(redis.call("LINDEX", key, -1)) < now then
+          return function ()
+            redis.call("LPUSH", key, now + period)
+            redis.call("LTRIM", key, 0, limit - 1)
+            redis.call("EXPIRE", key, period)
+          end
+        end
+      end,
+
+      concurrency = function (strategy)
+        local key, limit, ttl = strategy.key, strategy.limit, strategy.ttl
+
+        redis.call("ZREMRANGEBYSCORE", key, "-inf", "(" .. now)
+
+        if redis.call("ZCARD", key) < limit or redis.call("ZSCORE", key, token) then
+          return function ()
+            redis.call("ZADD", key, now + ttl, token)
+            redis.call("EXPIRE", key, ttl)
+          end
+        end
+      end
+    }
+
+    for _, strategy in ipairs(params.strategies) do
+      local lock = acquire[strategy.name](strategy)
+
+      if lock then
+        table.insert(locks, lock)
+      else
+        return 1
+      end
+    end
+
+    for _, lock in ipairs(locks) do
+      lock()
+    end
+
+    return 0
+  end
+}
+
+commands.RELEASE = {
+  params = { "strategies", "token" },
+  handler = function (params)
+    for _, strategy in ipairs(params.strategies) do
+      if "concurrency" == strategy.name then
+        redis.call("ZREM", strategy.key, params.token)
+      end
+    end
+
+    return redis.status_reply("ok")
+  end
+}
+
+commands.RESET = {
+  params = { "strategies" },
+  handler = function (params)
+    for _, strategy in ipairs(params.strategies) do
+      redis.call("DEL", strategy.key)
+    end
+
+    return redis.status_reply("ok")
+  end
+}
+
+commands.INFO = {
+  params = { "strategies", "timestamp" },
+  handler = function (params)
+    local usage, now = {}, params.timestamp
+
+    for _, strategy in ipairs(params.strategies) do
+      local key = strategy.key
+
+      if "concurrency" == strategy.name then
+        redis.call("ZREMRANGEBYSCORE", key, "-inf", "(" .. now)
+        table.insert(usage, redis.call("ZCARD", key))
+      elseif "rate_limit" == strategy.name then
+        local last = tonumber(redis.call("LINDEX", key, -1) or now)
+
+        while last < now do
+          redis.call("RPOP", key)
+          last = tonumber(redis.call("LINDEX", key, -1) or now)
+        end
+
+        table.insert(usage, redis.call("LLEN", key))
+      end
+    end
+
+    return usage
+  end
+}
+
+local function parse_params (parts)
+  local parse = {}
+
+  function parse.strategies (pos)
+    local strategies = {}
+
+    while pos + 3 <= #ARGV do
+      local name, strategy = string.lower(ARGV[pos]), nil
+      local bucket, limit, ttl_or_period = ARGV[pos + 1], tonumber(ARGV[pos + 2]), tonumber(ARGV[pos + 3])
+
+      if "concurrency" == name then
+        strategy = { name = name, bucket = bucket, limit = limit, ttl = ttl_or_period }
+      elseif "rate_limit" == name then
+        strategy = { name = name, bucket = bucket, limit = limit, period = ttl_or_period }
+      else
+        break
+      end
+
+      if bucket and 0 < limit and 0 < ttl_or_period then
+        strategy.key = table.concat({ KEYS[1], name, bucket, limit, ttl_or_period }, ":")
+        table.insert(strategies, strategy)
+
+        pos = pos + 4
+      else
+        return { err = "invalid " .. name .. " options" }
+      end
+    end
+
+    if 0 == #strategies then
+      return { err = "missing strategies" }
+    end
+
+    return { val = strategies, pos = pos }
+  end
+
+  function parse.token (pos)
+    if ARGV[pos] and ARGV[pos + 1] and "TOKEN" == string.upper(ARGV[pos]) then
+      return { val = ARGV[pos + 1], pos = pos + 2 }
+    end
+
+    return { err = "missing or invalid token" }
+  end
+
+  function parse.timestamp (pos)
+    if ARGV[pos] and ARGV[pos + 1] and "TS" == string.upper(ARGV[pos]) then
+      local timestamp = tonumber(ARGV[pos + 1])
+
+      if 0 < timestamp then
+        return { val = timestamp, pos = pos + 2 }
+      end
+    end
+
+    return { err = "missing or invalid timestamp" }
+  end
+
+  local params, pos = {}, 2
+
+  for _, part in ipairs(parts) do
+    local out = parse[part](pos)
+
+    if out.err then
+      return out
+    end
+
+    params[part] = out.val
+    pos = out.pos
+  end
+
+  if pos < #ARGV then
+    return { err = "wrong number of arguments" }
+  end
+
+  return { val = params }
+end
+
+local command = commands[string.upper(ARGV[1])]
+if not command then
+  return redis.error_reply("invalid command")
+end
+
+local params = parse_params(command.params)
+if params.err then
+  return redis.error_reply(params.err)
+end
+
+return command.handler(params.val)

data/lib/redis/throttle/api.rb

@@ -0,0 +1,120 @@
+# 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

@@ -0,0 +1,45 @@
+# 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,42 +1,76 @@
 # frozen_string_literal: true
 
-require_relative "./script"
-
 class Redis
-  module Throttle
+  class Throttle
     class Concurrency
-      SCRIPT = Script.new(File.read("#{__dir__}/concurrency.lua"))
-      private_constant :SCRIPT
+      # @!attribute [r] bucket
+      #   @return [String] Throttling group name
+      attr_reader :bucket
+
+      # @!attribute [r] limit
+      #   @return [Integer] Max allowed concurrent units
+      attr_reader :limit
 
-      # @param bucket [#to_s]
-      # @param limit [#to_i]
-      # @param ttl [#to_i]
+      # @!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
+        @bucket = -bucket.to_s
         @limit  = limit.to_i
         @ttl    = ttl.to_i
       end
 
-      # @param redis [Redis, Redis::Namespace]
-      # @param token [#to_s]
+      # 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 acquire(redis, token:)
-        SCRIPT
-          .call(redis, :keys => [@bucket], :argv => [token.to_s, @limit, @ttl, Time.now.to_i])
-          .zero?
+      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
 
-      # @param redis [Redis, Redis::Namespace]
-      # @param token [#to_s]
-      # @return [void]
-      def release(redis, token:)
-        redis.zrem(@bucket, token.to_s)
+      # @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
 
-      # @param redis [Redis, Redis::Namespace]
-      # @return [void]
-      def reset(redis)
-        redis.del(@bucket)
+      # @api private
+      #
+      # @return [Array(Integer, Integer)] Strategy complexity pseudo-score
+      def complexity
+        [1, @limit]
       end
     end
   end

data/lib/redis/throttle/errors.rb

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

data/lib/redis/throttle/rate_limit.rb

@@ -0,0 +1,75 @@
+# 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

@@ -6,9 +6,10 @@ require "redis/errors"
 require_relative "./errors"
 
 class Redis
-  module Throttle
-    # Simple helper to run script by it's sha1 digest with fallbak to script
-    # load if it was not loaded yet.
+  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"
@@ -16,29 +17,31 @@ class Redis
 
       LUA_ERROR_MESSAGE = %r{
         ERR\s
-        (?<message>Error\s(?:compiling|running)\sscript\s\(.*?\)):\s
-        (?:[^:]+:\d+:\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)
+        @digest = Digest::SHA1.hexdigest(@source).freeze
       end
 
       def call(redis, keys: [], argv: [])
-        __call__(redis, :keys => keys, :argv => argv)
+        __eval__(redis, keys, argv)
       rescue Redis::CommandError => e
         md = LUA_ERROR_MESSAGE.match(e.message.to_s)
         raise unless md
 
-        raise LuaError, [md[:message], md[:details]].compact.join(": ")
+        raise ScriptError, "#{md[:message]} @#{md[:loc]}: #{md[:details]}"
       end
 
       private
 
-      def __call__(redis, keys:, argv:)
+      def __eval__(redis, keys, argv)
         redis.evalsha(@digest, keys, argv)
       rescue Redis::CommandError => e
         raise unless e.message.include?(NOSCRIPT)

data/lib/redis/throttle/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis-throttle
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Alexey Zapparov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-18 00:00:00.000000000 Z
+date: 2020-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -28,16 +28,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0'
 description: 
 email:
 - alexey@zapparov.com
@@ -45,25 +45,24 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGES.md
 - LICENSE.txt
-- README.md
 - lib/redis/throttle.rb
-- lib/redis/throttle/concurrency.lua
+- 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/threshold.lua
-- lib/redis/throttle/threshold.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/v0.0.1
+  source_code_uri: https://gitlab.com/ixti/redis-throttle/tree/v1.0.0
   bug_tracker_uri: https://gitlab.com/ixti/redis-throttle/issues
-  changelog_uri: https://gitlab.com/ixti/redis-throttle/blob/v0.0.1/CHANGES.md
+  changelog_uri: https://gitlab.com/ixti/redis-throttle/blob/v1.0.0/CHANGES.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -72,7 +71,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -82,5 +81,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Redis based threshold and concurrency throttling.
+summary: Redis based rate limit and concurrency throttling.
 test_files: []

data/CHANGES.md

@@ -1,7 +0,0 @@
-# v0.0.1 (2020-08-17)
-
-* Initial release. Effectively this version represents extraction of concurrency
-  and threshold strategies from [sidekiq-throttled][].
-
-
-[sidekiq-throttled]: https://github.com/sensortower/sidekiq-throttled

data/README.md

@@ -1,123 +0,0 @@
-# Redis::Throttle
-
-[Redis](https://redis.io/) based threshold and concurrency throttling.
-
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem "redis-throttle"
-```
-
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install redis-throttle
-
-
-## Usage
-
-### Limit concurrency
-
-``` ruby
-# Allow 1 concurrent calls. If call takes more than 10 seconds, consider it
-# gone (as if process died, or by any other reason did not called `#release`):
-concurrency = Redis::Throttle::Concurrency.new(:bucket_name,
-  :limit => 1,
-  :ttl   => 10
-)
-
-concurrency.acquire(Redis.current, :token => "abc") # => true
-concurrency.acquire(Redis.current, :token => "xyz") # => false
-
-concurrency.release(Redis.current, :token => "abc")
-
-concurrency.acquire(Redis.current, :token => "xyz") # => true
-```
-
-### Limit threshold
-
-``` ruby
-# Allow 1 calls per 10 seconds:
-threshold = Redis::Throttle::Threshold.new(:bucket_name,
-  :limit  => 1,
-  :period => 10
-)
-
-threshold.acquire(Redis.current) # => true
-threshold.acquire(Redis.current) # => false
-
-sleep 10
-
-threshold.acquire(Redis.current) # => true
-```
-
-
-## Supported Ruby Versions
-
-This library aims to support and is tested against:
-
-* Ruby
-  * MRI 2.4.x
-  * MRI 2.5.x
-  * MRI 2.6.x
-  * MRI 2.7.x
-  * JRuby 9.2.x
-
-* [redis-rb](https://github.com/redis/redis-rb)
-  * 4.0.x
-  * 4.1.x
-  * 4.2.x
-
-* [redis-namespace](https://github.com/resque/redis-namespace)
-  * 1.6.x
-  * 1.7.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.
-
-
-## Development
-
-After checking out the repo, run `bundle install` to install dependencies.
-Then, run `bundle exec rake spec` to run the tests with ruby-rb client.
-
-To install this gem onto your local machine, run `bundle exec rake install`.
-To release a new version, update the version number in `version.rb`, and then
-run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and tags, and push the `.gem` file to [rubygems.org][].
-
-
-## Contributing
-
-* Fork redis-throttle
-* Make your changes
-* Ensure all tests pass (`bundle exec rake`)
-* Send a merge request
-* If we like them we'll merge them
-* If we've accepted a patch, feel free to ask for commit access!
-
-
-## Copyright
-
-Copyright (c) 2020 Alexey Zapparov<br>
-See [LICENSE.txt][] for further details.
-
-
-[LICENSE.txt]: https://gitlab.com/ixti/redis-throttle/blob/master/LICENSE.txt

data/lib/redis/throttle/concurrency.lua

@@ -1,13 +0,0 @@
-local bucket, token, limit, ttl, now =
-  KEYS[1], ARGV[1], tonumber(ARGV[2]), tonumber(ARGV[3]), tonumber(ARGV[4])
-
-redis.call("ZREMRANGEBYSCORE", bucket, "-inf", "(" .. now)
-
-if limit <= redis.call("ZCARD", bucket) and not redis.call("ZSCORE", bucket, token) then
-  return 1
-end
-
-redis.call("ZADD", bucket, now + ttl, token)
-redis.call("EXPIRE", bucket, ttl)
-
-return 0

data/lib/redis/throttle/threshold.lua

@@ -1,12 +0,0 @@
-local bucket, limit, period, now =
-  KEYS[1], tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
-
-if limit <= redis.call("LLEN", bucket) and now - redis.call("LINDEX", bucket, -1) < period then
-  return 1
-end
-
-redis.call("LPUSH", bucket, now)
-redis.call("LTRIM", bucket, 0, limit - 1)
-redis.call("EXPIRE", bucket, period)
-
-return 0

data/lib/redis/throttle/threshold.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "./script"
-
-class Redis
-  module Throttle
-    class Threshold
-      SCRIPT = Script.new(File.read("#{__dir__}/threshold.lua"))
-      private_constant :SCRIPT
-
-      NOOP = ->(_) { nil }
-      private_constant :NOOP
-
-      # @param bucket [#to_s]
-      # @param limit [#to_i]
-      # @param period [#to_i]
-      def initialize(bucket, limit:, period:)
-        @bucket = bucket.to_s
-        @limit  = limit.to_i
-        @period = period.to_i
-      end
-
-      # @param redis [Redis, Redis::Namespace]
-      # @return [Boolean]
-      def acquire(redis)
-        SCRIPT
-          .call(redis, :keys => [@bucket], :argv => [@limit, @period, Time.now.to_i])
-          .zero?
-      end
-
-      # @param redis [Redis, Redis::Namespace]
-      # @return [void]
-      def reset(redis)
-        redis.del(@bucket)
-      end
-    end
-  end
-end