prop 2.0.4 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d1514cf2a39e3ae5f63e5f2d7dfeec339883184
-  data.tar.gz: 7efc4b49b0511ed461e04bf65852617b63cac69e
+  metadata.gz: 7f2dd0390e5bbcf9ae63a8f2955d271b307b4d50
+  data.tar.gz: 66836a3d9ccb4189bc45edd01a94714d051eb620
 SHA512:
-  metadata.gz: a0103f6e80ec442f822af2177d2cab2c38a0b816f19b4020375d641d4309947a381a9951900544a6d3008286d58d9c293904a43d04e1560390a9c32fad0b10a7
-  data.tar.gz: c1f53ecb59e604b0d58e5ca166f8b826b7c78ba13889a09a4791fc6bb4ac12132f449d2305a77e1402f955e3b06a0e1821bf9b3ee768332feffa6deec3eaed46
+  metadata.gz: 8eab2e9e05c2a3c7e9e7b4cc84c483f532eccfbf86559c10f44df4dc03f6f267a5054f55a9a82f1fe9fe22744841638520dcb98e3d31063e441c04c8cae06b7f
+  data.tar.gz: dbc80fce9d3466f41194c4595dd4e3847d82879225c0ae8c5bae0a3903dfc8345792b36ce8447a7f3cc31cdf54a8900ab222e5e1dc3f9bf302ab615da5e8bb7a

data/README.md

@@ -184,6 +184,33 @@ rescue Prop::RateLimited => e
 end
 ```
 
+## First throttled
+
+You can opt to be notified when the throttle is breached for the first time.<br/>
+This can be used to send notifications on breaches but prevent spam on multiple throttle breaches.
+
+```Ruby
+Prop.configure(:mails_per_hour, threshold: 100, interval: 1.hour, first_throttled: true)
+
+throttled = Prop.throttle(:mails_per_hour, user.id, increment: 60)
+if throttled
+  if throttled == :first_throttled
+    ApplicationMailer.spammer_warning(user).deliver_now
+  end
+  Rails.logger.warn("Not sending emails")
+else
+  send_emails
+end
+
+# return values of throttle are: false, :first_throttled, true
+
+Prop.first_throttled(:mails_per_hour, 1, increment: 60) # -> false
+Prop.first_throttled(:mails_per_hour, 1, increment: 60) # -> :first_throttled
+Prop.first_throttled(:mails_per_hour, 1, increment: 60) # -> true
+
+# can also be accesses on `Prop::RateLimited` exceptions as `.first_throttled` 
+```
+
 ## Using Leaky Bucket Algorithm
 
 You can add two additional configurations: `:strategy` and `:burst_rate` to use the 

data/lib/prop.rb

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

data/lib/prop/interval_strategy.rb

@@ -5,6 +5,10 @@ require 'prop/key'
 module Prop
   class IntervalStrategy
     class << self
+      def zero_counter
+        0
+      end
+
       def counter(cache_key, options)
         Prop::Limiter.cache.read(cache_key).to_i
       end
@@ -17,7 +21,7 @@ module Prop
       end
 
       def reset(cache_key)
-        Prop::Limiter.cache.write(cache_key, 0, raw: true)
+        Prop::Limiter.cache.write(cache_key, zero_counter, raw: true)
       end
 
       def compare_threshold?(counter, operator, options)
@@ -25,6 +29,10 @@ module Prop
         counter.send operator, options.fetch(:threshold)
       end
 
+      def first_throttled?(counter, options)
+        (counter - options.fetch(:increment, 1)) <= options.fetch(:threshold)
+      end
+
       # Builds the expiring cache key
       def build(options)
         key       = options.fetch(:key)

data/lib/prop/leaky_bucket_strategy.rb

@@ -7,7 +7,7 @@ module Prop
   class LeakyBucketStrategy
     class << self
       def counter(cache_key, options)
-        bucket = Prop::Limiter.cache.read(cache_key) || default_bucket
+        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)
 
@@ -26,7 +26,7 @@ module Prop
       end
 
       def reset(cache_key)
-        Prop::Limiter.cache.write(cache_key, default_bucket)
+        Prop::Limiter.cache.write(cache_key, zero_counter)
       end
 
       def compare_threshold?(counter, operator, options)
@@ -53,13 +53,15 @@ module Prop
         Prop::IntervalStrategy.validate_options!(options)
 
         if !options[:burst_rate].is_a?(Fixnum) || options[:burst_rate] < options[:threshold]
-          raise ArgumentError.new(":burst_rate must be an Integer and larger than :threshold")
+          raise ArgumentError.new(":burst_rate must be an Integer and not less than :threshold")
         end
-      end
 
-      private
+        if options[:first_throttled]
+          raise ArgumentError.new(":first_throttled is not supported")
+        end
+      end
 
-      def default_bucket
+      def zero_counter
         { bucket: 0, last_updated: 0 }
       end
     end

data/lib/prop/limiter.rb

@@ -70,21 +70,9 @@ module Prop
       # (optional) a block of code that this throttle is guarding
       #
       # Returns true if the threshold for this handle has been reached, else returns false
-      def throttle(handle, key = nil, options = {})
-        return false if disabled?
-
+      def throttle(handle, key = nil, options = {}, &block)
         options, cache_key = prepare(handle, key, options)
-        counter = @strategy.increment(cache_key, options)
-
-        if @strategy.compare_threshold?(counter, :>, options)
-          before_throttle_callback &&
-            before_throttle_callback.call(handle, key, options[:threshold], options[:interval])
-
-          true
-        else
-          yield if block_given?
-          false
-        end
+        _throttle(handle, key, cache_key, options, &block).first
       end
 
       # Public: Records a single action for the given handle/key combination.
@@ -96,14 +84,19 @@ 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 = {})
+      def throttle!(handle, key = nil, options = {}, &block)
         options, cache_key = prepare(handle, key, options)
-
-        if throttle(handle, key, options)
-          raise Prop::RateLimited.new(options.merge(cache_key: cache_key, handle: handle))
+        throttled, counter = _throttle(handle, key, cache_key, options, &block)
+
+        if throttled
+          raise Prop::RateLimited.new(options.merge(
+            cache_key: cache_key,
+            handle: handle,
+            first_throttled: (throttled == :first_throttled)
+          ))
         end
 
-        block_given? ? yield : @strategy.counter(cache_key, options)
+        block_given? ? yield : counter
       end
 
       # Public: Is the given handle/key combination currently throttled ?
@@ -148,6 +141,28 @@ module Prop
 
       private
 
+      def _throttle(handle, key, cache_key, options)
+        return [false, @strategy.zero_counter] if disabled?
+
+        counter = @strategy.increment(cache_key, 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)
+            :first_throttled
+          else
+            true
+          end
+
+          [result, counter]
+        else
+          yield if block_given?
+          [false, counter]
+        end
+      end
+
       def disabled?
         !!@disabled
       end

data/lib/prop/rate_limited.rb

@@ -1,23 +1,21 @@
 module Prop
   class RateLimited < StandardError
-    attr_accessor :handle, :cache_key, :retry_after, :description
+    attr_accessor :handle, :cache_key, :retry_after, :description, :first_throttled
 
     def initialize(options)
-      handle    = options.fetch(:handle)
-      cache_key = options.fetch(:cache_key)
-      interval  = options.fetch(:interval).to_i
-      strategy  = options.fetch(:strategy)
-
-      super(strategy.threshold_reached(options))
-
+      self.handle    = options.fetch(:handle)
+      self.cache_key = options.fetch(:cache_key)
+      self.first_throttled = options.fetch(:first_throttled)
       self.description = options[:description]
-      self.handle      = handle
-      self.cache_key   = cache_key
+
+      interval  = options.fetch(:interval).to_i
       self.retry_after = interval - Time.now.to_i % interval
+
+      super(options.fetch(:strategy).threshold_reached(options))
     end
 
     def config
-      Prop.configurations[@handle]
+      Prop.configurations.fetch(@handle)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prop
 version: !ruby/object:Gem::Version
-  version: 2.0.4
+  version: 2.1.0
 platform: ruby
 authors:
 - Morten Primdahl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-17 00:00:00.000000000 Z
+date: 2016-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake