redis-throttle 0.0.1 → 1.1.0

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,86 +1,87 @@
 --- !ruby/object:Gem::Specification
 name: redis-throttle
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Alexey Zapparov
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-18 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: '2.0'
-  type: :development
+        version: 2.2.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
-description: 
+        version: 2.2.0
+description:
 email:
 - alexey@zapparov.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGES.md
 - LICENSE.txt
-- README.md
+- README.adoc
+- lib/redis-throttle.rb
 - lib/redis/throttle.rb
-- lib/redis/throttle/concurrency.lua
-- lib/redis/throttle/concurrency.rb
-- lib/redis/throttle/errors.rb
-- lib/redis/throttle/script.rb
-- lib/redis/throttle/threshold.lua
-- lib/redis/throttle/threshold.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/v0.0.1
+  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/v0.0.1/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.5'
+      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 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/concurrency.rb

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

data/lib/redis/throttle/errors.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-class Redis
-  module Throttle
-    class Error < StandardError; end
-    class LuaError < Error; end
-  end
-end