prop 2.2.5 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d749e4483b80fc4abe3ab44ba034c349bafaf521dc00c4ad059e3e9bc683e88a
-  data.tar.gz: d00a838d4b8f14cf9eb5a440e6a6fce475f6fb09d9937e2ebf6c0d66701ef82e
+  metadata.gz: bf33dac797d0f3b3cf7126709f1622e3069b7cf476f0bfde211178b3e4e743e1
+  data.tar.gz: e166a98af608dab54400289bb8fd28738b4ba8ab18ee0604613e75907ae4ec5c
 SHA512:
-  metadata.gz: 36474a7d324d76381193d6e39928e1a9e07ba6e15e2bbec050db8bff9d3d2f0eeb4fb713f3882864fbc4ef3c65bb5343a7d99ae6ecf588326c62e1672da28274
-  data.tar.gz: f68780e2c3cc1196a10e24e14949b8ee9b348d72c321bf4aa98e918031b423bf467ccefdda0cbd77dfdb9090403603540358b3a3561bbd17e6ce46d705cf7b72
+  metadata.gz: 953571f21e59adbbd743490543fa4a7faf30b0e07951f3646bf7e3af5043ed2e24d0f93c6c5d375b1bb866ed5719e1eefe206bf4ce230b5001d80a7fc0f48cee
+  data.tar.gz: ca8960bee3c4f2789d4ddc9a07e489ee646c45cbbe9391da6b76f7e06f81711224093806e60a49f85cd5f1451389868f22b58f1259283b33cf7ffad21665948b

data/README.md

@@ -18,7 +18,7 @@ To store values, prop needs a cache:
 Prop.cache = Rails.cache # needs read/write/increment methods
 ```
 
-Prop does not expire its used keys, so use memcached or similar, not redis.
+When using the interval strategy, prop sets a key expiry to its interval.  Because the leaky bucket strategy does not set a ttl, it is best to use memcached or similar for all prop caching, not redis.
 
 ## Setting a Callback
 
@@ -37,6 +37,9 @@ Example: Limit on accepted emails per hour from a given user, by defining a thre
 
 ```ruby
 Prop.configure(:mails_per_hour, threshold: 100, interval: 1.hour, description: "Mail rate limit exceeded")
+
+# Block requests by setting threshold to 0
+Prop.configure(:mails_per_hour, threshold: 0, interval: 1.hour, description: "All mail is blocked")
 ```
 
 ```ruby
@@ -224,6 +227,8 @@ You can add two additional configurations: `:strategy` and `:burst_rate` to use
 Prop will handle the details after configured, and you don't have to specify `:strategy` 
 again when using `throttle`, `throttle!` or any other methods.
 
+The leaky bucket algorithm used is "leaky bucket as a meter".
+
 ```ruby
 Prop.configure(:api_request, strategy: :leaky_bucket, burst_rate: 20, threshold: 5, interval: 1.minute)
 ```

data/lib/prop.rb

@@ -3,7 +3,7 @@ require "prop/limiter"
 require "forwardable"
 
 module Prop
-  VERSION = "2.2.5"
+  VERSION = "2.6.0"
 
   # Short hand for accessing Prop::Limiter methods
   class << self

data/lib/prop/interval_strategy.rb

@@ -16,16 +16,16 @@ module Prop
       # options argument is kept for api consistency for all strategies
       def increment(cache_key, amount, options = {})
         raise ArgumentError, "Change amount must be a Integer, was #{amount.class}" unless amount.is_a?(Integer)
-        cache.increment(cache_key, amount) || (cache.write(cache_key, amount, raw: true) && amount) # WARNING: potential race condition
+        cache.increment(cache_key, amount) || (cache.write(cache_key, amount, raw: true, expires_in: options.fetch(:interval, nil)) && amount) # WARNING: potential race condition
       end
 
       def decrement(cache_key, amount, options = {})
         raise ArgumentError, "Change amount must be a Integer, was #{amount.class}" unless amount.is_a?(Integer)
-        cache.decrement(cache_key, amount) || (cache.write(cache_key, 0, raw: true) && 0) # WARNING: potential race condition
+        cache.decrement(cache_key, amount) || (cache.write(cache_key, 0, raw: true, expires_in: options.fetch(:interval, nil)) && 0) # WARNING: potential race condition
       end
 
-      def reset(cache_key)
-        cache.write(cache_key, zero_counter, raw: true)
+      def reset(cache_key, options = {})
+        cache.write(cache_key, zero_counter, raw: true, expires_in: options.fetch(:interval, nil))
       end
 
       def compare_threshold?(counter, operator, options)
@@ -56,8 +56,8 @@ module Prop
       end
 
       def validate_options!(options)
-        validate_positive_integer(options[:threshold], :threshold)
-        validate_positive_integer(options[:interval], :interval)
+        validate_threshold(options[:threshold], :threshold)
+        validate_interval(options[:interval], :interval)
 
         amount = options[:increment] || options[:decrement]
         if amount
@@ -67,7 +67,11 @@ module Prop
 
       private
 
-      def validate_positive_integer(option, key)
+      def validate_threshold(option, key)
+        raise ArgumentError.new("#{key.inspect} must be a non-negative Integer") if !option.is_a?(Integer) || option < 0
+      end
+
+      def validate_interval(option, key)
         raise ArgumentError.new("#{key.inspect} must be a positive Integer") if !option.is_a?(Integer) || option <= 0
       end
 

data/lib/prop/leaky_bucket_strategy.rb

@@ -5,39 +5,69 @@ require 'prop/key'
 module Prop
   class LeakyBucketStrategy
     class << self
+      def _throttle_leaky_bucket(handle, key, cache_key, options)
+        (over_limit, bucket) = options.key?(:decrement) ?
+          decrement(cache_key, options.fetch(:decrement), options) :
+          increment(cache_key, options.fetch(:increment, 1), options)
+
+        [over_limit, bucket]
+      end
+
       def counter(cache_key, options)
-        bucket = Prop::Limiter.cache.read(cache_key) || zero_counter
-        now = Time.now.to_i
-        leak_amount = (now - bucket.fetch(:last_updated)) / options.fetch(:interval) * options.fetch(:threshold)
+        cache.read(cache_key) || zero_counter
+      end
+
+      def leak_amount(bucket, amount, options, now)
+        leak_rate = (now - bucket.fetch(:last_leak_time, 0)) / options.fetch(:interval).to_f
+        leak_amount = (leak_rate * options.fetch(:threshold).to_f)
+        leak_amount.to_i
+      end
 
-        bucket[:bucket] = [bucket.fetch(:bucket) - leak_amount, 0].max
-        bucket[:last_updated] = now
-        bucket
+      def update_bucket(current_bucket_size, max_bucket_size, amount)
+        over_limit = (max_bucket_size-current_bucket_size) < amount
+        updated_bucket_size = over_limit ? current_bucket_size : current_bucket_size + amount
+        [over_limit, updated_bucket_size]
       end
 
       # WARNING: race condition
       # this increment is not atomic, so it might miss counts when used frequently
       def increment(cache_key, amount, options)
-        counter = counter(cache_key, options)
-        counter[:bucket] += amount
-        Prop::Limiter.cache.write(cache_key, counter)
-        counter
+        bucket = counter(cache_key, options)
+        now = Time.now.to_i
+        max_bucket_size = options.fetch(:burst_rate)
+        current_bucket_size = bucket.fetch(:bucket, 0)
+        leak_amount = leak_amount(bucket, amount, options, now)
+        if leak_amount > 0
+          # maybe TODO, update last_leak_time to reflect the exact time for the current leak amount
+          # the current strategy will always reflect a little less leakage, probably not an issue though
+          bucket[:last_leak_time] = now
+          current_bucket_size = [(current_bucket_size - leak_amount), 0].max
+        end
+
+        over_limit, updated_bucket_size = update_bucket(current_bucket_size, max_bucket_size, amount)
+        bucket[:bucket] = updated_bucket_size
+        bucket[:over_limit] = over_limit
+        cache.write(cache_key, bucket)
+        [over_limit, bucket]
       end
 
       def decrement(cache_key, amount, options)
-        counter = counter(cache_key, options)
-        counter[:bucket] -= amount
-        counter[:bucket] = 0 unless counter[:bucket] > 0
-        Prop::Limiter.cache.write(cache_key, counter)
-        counter
+        now = Time.now.to_i
+        bucket = counter(cache_key, options)
+        leak_amount = leak_amount(bucket, amount, options, now)
+        bucket[:bucket] = [bucket[:bucket] - amount - leak_amount, 0].max
+        bucket[:last_leak_time] = now if leak_amount > 0
+        bucket[:over_limit] = false
+        cache.write(cache_key, bucket)
+        [false, bucket]
       end
 
-      def reset(cache_key)
-        Prop::Limiter.cache.write(cache_key, zero_counter)
+      def reset(cache_key, options = {})
+        cache.write(cache_key, zero_counter, raw: true)
       end
 
-      def compare_threshold?(counter, operator, options)
-        counter.fetch(:bucket).to_i.send operator, options.fetch(:burst_rate)
+      def compare_threshold?(bucket, operator, options)
+        bucket.fetch(:over_limit, false)
       end
 
       def build(options)
@@ -69,7 +99,11 @@ module Prop
       end
 
       def zero_counter
-        { bucket: 0, last_updated: 0 }
+        { bucket: 0, last_leak_time: 0, over_limit: false }
+      end
+
+      def cache
+        Prop::Limiter.cache
       end
     end
   end

data/lib/prop/limiter.rb

@@ -46,8 +46,7 @@ module Prop
       #
       # Raises Prop::RateLimited if the number if the threshold for this handle has been reached
       def configure(handle, defaults)
-        raise ArgumentError.new("Invalid threshold setting") unless defaults[:threshold].to_i > 0
-        raise ArgumentError.new("Invalid interval setting")  unless defaults[:interval].to_i > 0
+        Prop::Options.validate_options!(defaults)
 
         self.handles ||= {}
         self.handles[handle] = defaults
@@ -56,7 +55,7 @@ module Prop
       # Public: Disables Prop for a block of code
       #
       # block    - a block of code within which Prop will not raise
-      def disabled(&block)
+      def disabled(&_block)
         @disabled = true
         yield
       ensure
@@ -72,8 +71,8 @@ module Prop
       #
       # Returns true if the threshold for this handle has been reached, else returns false
       def throttle(handle, key = nil, options = {})
-        options, cache_key = prepare(handle, key, options)
-        throttled = _throttle(handle, key, cache_key, options).first
+        options, cache_key, strategy = prepare(handle, key, options)
+        throttled = _throttle(strategy, handle, key, cache_key, options).first
         block_given? && !throttled ? yield : throttled
       end
 
@@ -87,8 +86,8 @@ module Prop
       # Raises Prop::RateLimited if the threshold for this handle has been reached
       # Returns the value of the block if given a such, otherwise the current count of the throttle
       def throttle!(handle, key = nil, options = {}, &block)
-        options, cache_key = prepare(handle, key, options)
-        throttled, counter = _throttle(handle, key, cache_key, options)
+        options, cache_key, strategy = prepare(handle, key, options)
+        throttled, counter = _throttle(strategy, handle, key, cache_key, options)
 
         if throttled
           raise Prop::RateLimited.new(options.merge(
@@ -108,9 +107,9 @@ module Prop
       #
       # Returns true if a call to `throttle!` with same parameters would raise, otherwise false
       def throttled?(handle, key = nil, options = {})
-        options, cache_key = prepare(handle, key, options)
-        counter = @strategy.counter(cache_key, options)
-        @strategy.compare_threshold?(counter, :>=, options)
+        options, cache_key, strategy = prepare(handle, key, options)
+        counter = strategy.counter(cache_key, options)
+        strategy.compare_threshold?(counter, :>=, options)
       end
 
       # Public: Resets a specific throttle
@@ -120,8 +119,8 @@ module Prop
       #
       # Returns nothing
       def reset(handle, key = nil, options = {})
-        _options, cache_key = prepare(handle, key, options)
-        @strategy.reset(cache_key)
+        _options, cache_key, strategy = prepare(handle, key, options)
+        strategy.reset(cache_key, options)
       end
 
       # Public: Counts the number of times the given handle/key combination has been hit in the current window
@@ -131,8 +130,8 @@ module Prop
       #
       # Returns a count of hits in the current window
       def count(handle, key = nil, options = {})
-        options, cache_key = prepare(handle, key, options)
-        @strategy.counter(cache_key, options)
+        options, cache_key, strategy = prepare(handle, key, options)
+        strategy.counter(cache_key, options)
       end
       alias :query :count
 
@@ -143,18 +142,26 @@ module Prop
 
       private
 
-      def _throttle(handle, key, cache_key, options)
-        return [false, @strategy.zero_counter] if disabled?
+      def leaky_bucket_strategy?(strategy)
+        strategy == Prop::LeakyBucketStrategy
+      end
+
+      def _throttle(strategy, handle, key, cache_key, options)
+        return [false, strategy.zero_counter] if disabled?
+
+        if leaky_bucket_strategy?(strategy)
+          return Prop::LeakyBucketStrategy._throttle_leaky_bucket(handle, key, cache_key, options)
+        end
 
         counter = options.key?(:decrement) ?
-          @strategy.decrement(cache_key, options.fetch(:decrement), options) :
-          @strategy.increment(cache_key, options.fetch(:increment, 1), options)
+          strategy.decrement(cache_key, options.fetch(:decrement), options) :
+          strategy.increment(cache_key, options.fetch(:increment, 1), options)
 
-        if @strategy.compare_threshold?(counter, :>, options)
+        if strategy.compare_threshold?(counter, :>, options)
           before_throttle_callback &&
             before_throttle_callback.call(handle, key, options[:threshold], options[:interval])
 
-          result = if options[:first_throttled] && @strategy.first_throttled?(counter, options)
+          result = if options[:first_throttled] && strategy.first_throttled?(counter, options)
             :first_throttled
           else
             true
@@ -177,11 +184,11 @@ module Prop
 
         options = Prop::Options.build(key: key, params: params, defaults: defaults)
 
-        @strategy = options.fetch(:strategy)
+        strategy = options.fetch(:strategy)
 
-        cache_key = @strategy.build(key: key, handle: handle, interval: options[:interval])
+        cache_key = strategy.build(key: key, handle: handle, interval: options[:interval])
 
-        [ options, cache_key ]
+        [ options, cache_key, strategy ]
       end
     end
   end

data/lib/prop/options.rb

@@ -12,17 +12,24 @@ module Prop
       result   = defaults.merge(params)
 
       result[:key] = Prop::Key.normalize(key)
+      result[:strategy] = get_strategy(result)
 
-      result[:strategy] = if leaky_bucket.include?(result[:strategy])
+      result[:strategy].validate_options!(result)
+      result
+    end
+
+    def self.validate_options!(options)
+      get_strategy(options).validate_options!(options)
+    end
+
+    def self.get_strategy(options)
+      if leaky_bucket.include?(options[:strategy])
         Prop::LeakyBucketStrategy
-      elsif result[:strategy] == nil
+      elsif options[:strategy] == nil
         Prop::IntervalStrategy
       else
-        result[:strategy] # allowing any new/unknown strategy to be used
+        options[:strategy] # allowing any new/unknown strategy to be used
       end
-
-      result[:strategy].validate_options!(result)
-      result
     end
 
     def self.leaky_bucket

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prop
 version: !ruby/object:Gem::Version
-  version: 2.2.5
+  version: 2.6.0
 platform: ruby
 authors:
 - Morten Primdahl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-07 00:00:00.000000000 Z
+date: 2021-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -115,8 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Gem for implementing rate limits.