redis-throttle 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94cbed31445714a0f2883bfbe8e317dff6813db80d93c73b7a16a32dfb45524a
-  data.tar.gz: 5aa8ecb1c5d5301f314f844bbdbdd720d26d881b6820966cf42682302bd00178
+  metadata.gz: 6dbef2b5249fc1cd8ff9c199e00b11b98dafa0ec8f0a707e9da8af4c5fa3ed1d
+  data.tar.gz: 2a8ddfd1fe58e6f9a3e63cb219ab42450518f804cce806e7778aaca251563cb1
 SHA512:
-  metadata.gz: 89d197efa9dadad39539510da10ec183c2df3f00c1b12063591827ab7ffd02b368ab92a9643a20d83dc40751bbfa2cdf33ae42f2d41717d314d40f496628af53
-  data.tar.gz: d07140bc01e01b051dcabd266b0a2d5410ce9289d74b5550c44da903c8d3b0f5e574a8cef3ae5b777b26fb1d5557e2fb294e9b0a7394b75e77c0c31e047def75
+  metadata.gz: 74c91479a17ea0759cb6d9a9bcf78c27d1454339a3dca5678cb90aa28c582ed6f11f5d825ff38401a51e9a039728f3d4494887466674f2c29aae4615b376af41
+  data.tar.gz: 4e299f8ae32084daf1c5941629601ba48d4af09d5cec9504421e05a462e0be1a24131929c56c3913f5edf70b4aa53a3a8a57d0d72d90a494193695d8fffb3db5

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,157 @@
+= 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(redis, token: "abc") # => "abc"
+concurrency.acquire(redis, token: "xyz") # => nil
+
+concurrency.release(redis, token: "abc")
+
+concurrency.acquire(redis, 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(redis) # => "6a6c6546-268d-4216-bcf3-3139b8e11609"
+rate_limit.acquire(redis) # => nil
+
+sleep 10
+
+rate_limit.acquire(redis) # => "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(redis, 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(redis) do
+  # ...
+end
+----
+
+
+== 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
+** 4.7.x
+** 4.8.x
+** 5.0.x
+* https://github.com/resque/redis-namespace[redis-namespace]
+** 1.10.x
+* https://github.com/redis-rb/redis-client[redis-client]
+** 0.12.x
+** 0.13.x
+** 0.14.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*, *redis-namespace*,
+and *redis-client* 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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "./redis_throttle"

data/lib/redis_throttle/api.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+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, RedisClient, RedisClient::Decorator::Client]
+    def initialize(redis)
+      @redis = redis
+    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 = []
+      block   = ->(key) { from_key(key)&.then { |strategy| results << strategy } }
+
+      if redis_client?
+        @redis.scan("MATCH", "#{NAMESPACE}:*:#{match}:*:*", &block)
+      else
+        @redis.scan_each(match: "#{NAMESPACE}:*:#{match}:*:*", &block)
+      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
+
+    private
+
+    def redis_client?
+      return true if defined?(::RedisClient) && @redis.is_a?(::RedisClient)
+      return true if defined?(::RedisClient::Decorator::Client) && @redis.is_a?(::RedisClient::Decorator::Client)
+
+      false
+    end
+
+    def execute(command, argv)
+      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/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

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 = "2.0.0"
+end