redis-throttle 0.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6578fcf4ed5b682873d8f6c31a629bf8ab04fa3f747a6e85e67d552fa22ad40
-  data.tar.gz: c3d2ea3307187912af4d4f93ecee4f8a2fc2e386922511b63e3a9ad93e547c49
+  metadata.gz: df74619037a1515419ebbf8381326577c540376855146fece1b9624f9ee443f6
+  data.tar.gz: 4b465e4412d3fa8408b48470b867576457737524cded5b41ea8bb04aef53a39b
 SHA512:
-  metadata.gz: 861efde66ca39700db8a6922add9e7539ecd13b9ecea1a79fe14575df1ca75772ac49608a298bbdb92fce7ec7681cb40eeaf3768089e7481395c57eb6ad23418
-  data.tar.gz: a1299fb9d99b21c5cca90823812e77feda7fccc7ed4e69778afcd2bb87a0c74aa94f48746047f3fd8b02ccf2076d4344c4047ca499b69090bfffd823cdc6ae87
+  metadata.gz: cfcdaef05593dd858baef2d65ae0a1240cea10cbb3adda0989f5bba724672233c4ec8551040b746421a8d40eb5240a0338de5f027bafa3eabe6a3c6a28071c0d
+  data.tar.gz: e2a761f5962106a211ed285f527a73e24d040c414053a707c26fa11dad1b2477f73ecd38248b4ba639c32c47a773719af788dd02918af8259af1c283f100e979

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Alexey Zapparov
+Copyright (c) 2020-2021 Alexey Zapparov
 
 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,178 @@
+= RedisThrottle
+
+Redis based rate limit and concurrency throttling.
+
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+    $ bundle add redis-throttle
+
+Or install it yourself as:
+
+    $ gem install redis-throttle
+
+
+== Usage
+
+=== Concurrency Limit
+
+[source,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 = RedisThrottle.concurrency(:bucket_name,
+  :limit => 1,
+  :ttl   => 10
+)
+
+concurrency.acquire(:token => "abc") # => "abc"
+concurrency.acquire(:token => "xyz") # => nil
+
+concurrency.release(:token => "abc")
+
+concurrency.acquire(:token => "xyz") # => "xyz"
+----
+
+=== Rate Limit
+
+[source,ruby]
+----
+# Allow 1 calls per 10 seconds:
+rate_limit = RedisThrottle.rate_limit(:bucket_name,
+  :limit  => 1,
+  :period => 10
+)
+
+rate_limit.acquire # => "6a6c6546-268d-4216-bcf3-3139b8e11609"
+rate_limit.acquire # => nil
+
+sleep 10
+
+rate_limit.acquire # => "e2926a90-2cf4-4bff-9401-65f3a70d32bd"
+----
+
+
+=== Multi-strategy
+
+[source,ruby]
+----
+throttle = RedisThrottle
+  .concurrency(:db, :limit => 3, :ttl => 900)
+  .rate_limit(:api_minutely, :limit => 1, :period => 60)
+  .rate_limit(:api_hourly, :limit => 10, :period => 3600)
+
+throttle.call(:token => "abc") do
+  # do something if all strategies are resolved
+end
+----
+
+You can also compose multiple throttlers together:
+
+[source,ruby]
+----
+db_limiter  = RedisThrottle.concurrency(:db, :limit => 3, :ttl => 900)
+api_limiter = RedisThrottle
+  .rate_limit(:api_minutely, :limit => 1, :period => 60)
+  .rate_limit(:api_hourly, :limit => 10, :period => 3600)
+
+(db_limiter + api_limiter).call do
+  # ...
+end
+----
+
+
+=== With ConnectionPool
+
+If you're using [connection_pool](https://github.com/mperham/connection_pool),
+you can pass its `#with` method as connection builder:
+
+[source,ruby]
+----
+pool     = ConnectionPool.new { Redis.new }
+throttle = RedisThrottle.new(:redis => pool.method(:with))
+----
+
+=== With Sidekiq
+
+[Sidekiq](https://github.com/mperham/sidekiq): uses ConnectionPool, so you can
+use the same approach:
+
+[source,ruby]
+----
+throttle = RedisThrottle.new(:redis => Sidekiq.redis_pool.method(:with))
+----
+
+Or, you can use its `.redis` method directly:
+
+[source,ruby]
+----
+throttle = RedisThrottle.new(:redis => Sidekiq.method(:redis))
+----
+
+
+== Compatibility
+
+This library aims to support and is tested against:
+
+* https://www.ruby-lang.org[Ruby]
+** MRI 2.7.x
+** MRI 3.0.x
+** MRI 3.1.x
+** MRI 3.2.x
+* https://redis.io[Redis Server]
+** 6.0.x
+** 6.2.x
+** 7.0.x
+* https://github.com/redis/redis-rb[redis-rb]
+** 4.1.x
+** 4.2.x
+** 4.3.x
+** 4.4.x
+** 4.5.x
+** 4.6.x
+* https://github.com/resque/redis-namespace[redis-namespace]
+** 1.10.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.
+
+The same applies to *Redis Server*, *redis-rb*, and *redis-namespace* support.
+
+
+== Development
+
+  scripts/update-gemfiles
+  scripts/run-rspec
+  bundle exec rubocop
+
+
+== 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!
+
+
+== Appreciations
+
+Thanks to all how providede suggestions and criticism, especially to those who
+helped me shape some of the initial ideas:
+
+* https://gitlab.com/freemanoid[@freemanoid]
+* https://gitlab.com/petethepig[@petethepig]
+* https://gitlab.com/dervus[@dervus]

data/lib/redis/throttle.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
-require_relative "throttle/errors"
-require_relative "throttle/version"
-require_relative "throttle/concurrency"
-require_relative "throttle/threshold"
+require_relative "../redis_throttle"
 
-# @see https://github.com/redis/redis-rb
 class Redis
-  # Distributed threshold and concurrency throttling.
-  module Throttle; end
+  # @deprecated Use ::RedisThrottle
+  class Throttle < RedisThrottle
+    class << self
+      attr_accessor :silence_deprecation_warning
+    end
+
+    self.silence_deprecation_warning = false
+
+    def initialize(*args, **kwargs, &block)
+      super(*args, **kwargs, &block)
+
+      return if self.class.silence_deprecation_warning
+
+      warn "#{self.class} usage was deprecated, please use RedisThrottle instead"
+    end
+  end
 end

data/lib/redis-throttle.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "./redis_throttle"
+require_relative "./redis/throttle"

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,118 @@
+# frozen_string_literal: true
+
+require "redis"
+require "redis-prescription"
+
+require_relative "./concurrency"
+require_relative "./rate_limit"
+
+class RedisThrottle
+  # @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 = RedisPrescription.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.sort_by(&:itself)) << :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

data/lib/redis_throttle/class_methods.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "./api"
+
+class RedisThrottle
+  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

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