redis-throttle 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94cbed31445714a0f2883bfbe8e317dff6813db80d93c73b7a16a32dfb45524a
-  data.tar.gz: 5aa8ecb1c5d5301f314f844bbdbdd720d26d881b6820966cf42682302bd00178
+  metadata.gz: df74619037a1515419ebbf8381326577c540376855146fece1b9624f9ee443f6
+  data.tar.gz: 4b465e4412d3fa8408b48470b867576457737524cded5b41ea8bb04aef53a39b
 SHA512:
-  metadata.gz: 89d197efa9dadad39539510da10ec183c2df3f00c1b12063591827ab7ffd02b368ab92a9643a20d83dc40751bbfa2cdf33ae42f2d41717d314d40f496628af53
-  data.tar.gz: d07140bc01e01b051dcabd266b0a2d5410ce9289d74b5550c44da903c8d3b0f5e574a8cef3ae5b777b26fb1d5557e2fb294e9b0a7394b75e77c0c31e047def75
+  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,288 +1,22 @@
 # frozen_string_literal: true
 
-require "redis"
-require "set"
-require "securerandom"
+require_relative "../redis_throttle"
 
-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
+  # @deprecated Use ::RedisThrottle
+  class Throttle < RedisThrottle
+    class << self
+      attr_accessor :silence_deprecation_warning
     end
 
-    alias << merge!
+    self.silence_deprecation_warning = false
 
-    # 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)
+    def initialize(*args, **kwargs, &block)
+      super(*args, **kwargs, &block)
 
-      nil
-    end
+      return if self.class.silence_deprecation_warning
 
-    # 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)
+      warn "#{self.class} usage was deprecated, please use RedisThrottle instead"
     end
-
-    protected
-
-    attr_accessor :strategies
   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.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