prop 0.4.1 → 0.5.1

data/README.rdoc

@@ -17,60 +17,59 @@ You can choose to rely on a database or Moneta or Redis or whatever you'd like t
 
 Once the read and write operations are defined, you can optionally define some preconfigured default thresholds. If for example, you want to have a threshold on accepted emails per hour from a given user, you could define a threshold and interval (in seconds) for this like so:
 
-  Prop.setup(:mails_per_hour, :threshold => 100, :interval => 1.hour)
+  Prop.defaults(:mails_per_hour, :threshold => 100, :interval => 1.hour)
 
-This results in a the following methods being generated:
+You can now put the throttle to work with this values, by passing the "handle" to the respective methods in Prop:
 
   # Throws Prop::RateLimitExceededError if the threshold/interval has been reached
-  Prop.throttle_mails_per_hour!
+  Prop.throttle!(:mails_per_hour)
 
   # Returns true if the threshold/interval has been reached
-  Prop.throttle_mails_per_hour?
+  Prop.throttled?(:mails_per_hour)
 
-  # Sets the counter to 0
-  Prop.reset_mails_per_hour
+  # Sets the throttle "count" to 0
+  Prop.reset(:mails_per_hour)
+
+  # Returns the value of this throttle, usually a count, but see below for more
+  Prop.query(:mails_per_hour)
 
 In many cases you will want to tie a specific key to a defined throttle, for example you can scope the throttling to a specific sender rather than running a global "mails per hour" throttle:
 
-  Prop.throttle_mails_per_hour!(mail.from)
+  Prop.throttle!(:mails_per_hour, mail.from)
+  Prop.throttled?(:mails_per_hour, mail.from)
+  Prop.reset(:mails_per_hour, mail.from)
+  Prop.query(:mails_per_hour, mail.from)
+
+The throttle scope can also be an array of values, e.g.:
 
-If this method gets called more than "threshold" times within "interval in seconds" Prop throws a Prop::RateLimitExceededError. You can change the message of this error, which is handy when you are using Prop in multiple locations and want to be able to differentiate further up the stack. For example:
+  Prop.throttle!(:mails_per_hour, [ account.id, mail.from ])
 
-  Prop.setup(:logins, :threshold => 5, :interval => 5.minutes, :message => "Too many invalid login attempts.")
+If the throttle! method gets called more than "threshold" times within "interval in seconds" for a given handle and key combination, Prop throws a Prop::RateLimitExceededError. This exception contains a "handle" reference, which is handy when you are using Prop in multiple locations and want to be able to differentiate further up the stack. For example, in Rails you can use this in e.g. ApplicationController:
 
-In Rails you can use this in e.g. ApplicationController:
+  THROTTLE_MESSAGES = Hash.new("Throttle exceeded")
+  THROTTLE_MESSAGES[:login] = "Too many invalid login attempts. Try again later."
 
   rescue_from Prop::RateLimitExceededError do |exception|
-    render :status => 403, :message => exception.message
+    render :status => 403, :message => THROTTLE_MESSAGES[exception.handle]
   end
 
 You can chose to override the threshold for a given key:
 
-  Prop.throttle_mails_per_hour!(mail.from, :threshold => account.mail_throttle_threshold)
-
-If you wish to reset a specific throttle, you can do that like so:
-
-  Prop.reset_mails_per_hour(mail.from)
-
-When the threshold are invoked without argument, the key is nil and as such a scope of its own.
-
-The default (and smallest possible) increment is 1, you can of course set that to any integer value using :increment
+  Prop.throttle!(:mails_per_hour, mail.from, :threshold => account.mail_throttle_threshold)
 
-  Prop.setup(:execution_time_ms, :threshold => 1000, :interval => 1.minute)
-  Prop.throttle_execution_time_ms!(:increment => (Benchmark.realtime { execute } * 1000).to_i)
+When the threshold are invoked without argument, the key is nil and as such a scope of its own, i.e. these are equivalent:
 
-You can gauge the current value of a throttle using count:
+  Prop.throttle!(:mails_per_hour)
+  Prop.throttle!(:mails_per_hour, nil)
 
-  Prop.count_mails_per_hour!(mail.from)
+The default (and smallest possible) increment is 1, you can set that to any integer value using :increment which is handy for building time based throttles:
 
-Lastly you can use Prop without registering the thresholds up front:
+  Prop.setup(:execute_time, :threshold => 10, :interval => 1.minute)
+  Prop.throttle!(:execute_time, account.id, :increment => (Benchmark.realtime { execute }).to_i)
 
-  Prop.throttle!(:key => 'nuisance@example.com', :threshold => 100, :interval -> 1.hour)
-  Prop.throttle?(:key => 'nuisance@example.com', :threshold => 100, :interval -> 1.hour)
-  Prop.reset(:key => 'nuisance@example.com', :threshold => 100, :interval -> 1.hour)
-  Prop.count(:key => 'nuisance@example.com', :threshold => 100, :interval -> 1.hour)
+== How it works
 
-It's up to you to pass an appropriate key which reflects the scope you're rate limiting. The interval is tied to the underlying key generating mechanism, so if you change that between calls and have all other things equal, then that will result in different throttles being set.
+Prop uses the interval to define a window of time using simple div arithmetic. This means that it's a worst case throttle that will allow up to 2 times the specified requests within the specified interval.
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.1

data/lib/prop.rb

@@ -8,14 +8,12 @@ end
 
 class Prop
   class RateLimitExceededError < RuntimeError
-    attr_accessor :root_message, :retry_after
-
-    def self.create(key, threshold, message)
-      default = "#{key} threshold #{threshold} exceeded"
-      error   = new(message || default)
-      error.retry_after  = threshold - Time.now.to_i % threshold if threshold > 0
-      error.root_message = default
+    attr_accessor :handle, :retry_after
 
+    def self.create(handle, key, threshold)
+      error = new("#{handle} threshold of #{threshold} exceeded for key '#{key}'")
+      error.handle      = handle
+      error.retry_after = threshold - Time.now.to_i % threshold if threshold > 0
       raise error
     end
   end
@@ -31,69 +29,64 @@ class Prop
       self.writer = blk
     end
 
-    def setup(handle, defaults)
+    def defaults(handle, defaults)
       raise RuntimeError.new("Invalid threshold setting") unless defaults[:threshold].to_i > 0
-      raise RuntimeError.new("Invalid interval setting") unless defaults[:interval].to_i > 0
-
-      define_prop_class_method "throttle_#{handle}!" do |*args|
-        throttle!(sanitized_prop_options([ handle ] + args, defaults))
-      end
-
-      define_prop_class_method "throttle_#{handle}?" do |*args|
-        throttle?(sanitized_prop_options([ handle ] + args, defaults))
-      end
-
-      define_prop_class_method "reset_#{handle}" do |*args|
-        reset(sanitized_prop_options([ handle ] + args, defaults))
-      end
+      raise RuntimeError.new("Invalid interval setting")  unless defaults[:interval].to_i > 0
 
-      define_prop_class_method "count_#{handle}" do |*args|
-        count(sanitized_prop_options([ handle ] + args, defaults))
-      end
+      self.handles ||= {}
+      self.handles[handle] = defaults
     end
 
-    def throttle?(options)
-      count(options) >= options[:threshold]
-    end
-
-    def throttle!(options)
-      counter = count(options)
+    def throttle!(handle, key = nil, options = {})
+      options   = sanitized_prop_options(handle, key, options)
+      cache_key = sanitized_prop_key(key, options[:interval])
+      counter   = reader.call(cache_key).to_i
 
       if counter >= options[:threshold]
-        if options[:progressive]
-          writer.call(sanitized_prop_key(options.merge(:window_modifier => 1)), counter) 
-        end
-        raise Prop::RateLimitExceededError.create(options[:key], options[:threshold], options[:message])
+        raise Prop::RateLimitExceededError.create(handle, normalize_cache_key(key), options[:threshold])
       else
-        writer.call(sanitized_prop_key(options), counter + [ 1, options[:increment].to_i ].max)
+        writer.call(cache_key, counter + [ 1, options[:increment].to_i ].max)
       end
     end
 
-    def reset(options)
-      cache_key = sanitized_prop_key(options)
+    def throttled?(handle, key = nil, options = {})
+      options   = sanitized_prop_options(handle, key, options)
+      cache_key = sanitized_prop_key(key, options[:interval])
+
+      reader.call(cache_key).to_i >= options[:threshold]
+    end
+
+    def reset(handle, key = nil, options = {})
+      options   = sanitized_prop_options(handle, key, options)
+      cache_key = sanitized_prop_key(key, options[:interval])
+
       writer.call(cache_key, 0)
     end
 
-    def count(options)
-      cache_key = sanitized_prop_key(options)
+    def query(handle, key = nil, options = {})
+      options   = sanitized_prop_options(handle, key, options)
+      cache_key = sanitized_prop_key(key, options[:interval])
+
       reader.call(cache_key).to_i
     end
 
     private
 
     # Builds the expiring cache key
-    def sanitized_prop_key(options)
-      window    = (Time.now.to_i / options[:interval]) + options[:window_modifier].to_i
-      cache_key = "#{normalize_cache_key(options[:key])}/#{ window }"
+    def sanitized_prop_key(key, interval)
+      window    = (Time.now.to_i / interval)
+      cache_key = "#{normalize_cache_key(key)}/#{ window }"
       "prop/#{Digest::MD5.hexdigest(cache_key)}"
     end
 
     # Sanitizes the option set and sets defaults
-    def sanitized_prop_options(args, defaults)
-      options = args.last.is_a?(Hash) ? args.pop : {}
+    def sanitized_prop_options(handle, key, options)
+      defaults = (handles || {})[handle] || {}
       return {
-        :key => normalize_cache_key(args), :message => defaults[:message], :progressive => defaults[:progressive],
-        :threshold => defaults[:threshold].to_i, :interval => defaults[:interval].to_i, :increment => defaults[:increment]
+        :key       => normalize_cache_key(key),
+        :increment => defaults[:increment],
+        :threshold => defaults[:threshold].to_i,
+        :interval  => defaults[:interval].to_i
       }.merge(options)
     end
 

data/prop.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{prop}
-  s.version = "0.4.1"
+  s.version = "0.5.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Morten Primdahl"]
-  s.date = %q{2010-12-08}
+  s.date = %q{2011-02-03}
   s.description = %q{A gem for implementing rate limiting}
   s.email = %q{morten@zendesk.com}
   s.extra_rdoc_files = [
@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   ]
   s.files = [
     ".document",
+    ".gemtest",
     "LICENSE",
     "README.rdoc",
     "Rakefile",

data/test/test_prop.rb

@@ -12,167 +12,125 @@ class TestProp < Test::Unit::TestCase
       Time.stubs(:now).returns(@start)
     end
 
-    context "#configure" do
+    context "#defaults" do
       should "raise errors on invalid configuation" do
         assert_raises(RuntimeError) do
-          Prop.setup :hello_there, :threshold => 20, :interval => 'hello'
+          Prop.defaults :hello_there, :threshold => 20, :interval => 'hello'
         end
 
         assert_raises(RuntimeError) do
-          Prop.setup :hello_there, :threshold => 'wibble', :interval => 100
+          Prop.defaults :hello_there, :threshold => 'wibble', :interval => 100
         end
       end
 
-      should "accept a handle and an options hash" do
-        Prop.setup :hello_there, :threshold => 40, :interval => 100
-        assert Prop.respond_to?(:throttle_hello_there!)
-        assert Prop.respond_to?(:throttle_hello_there?)
-        assert Prop.respond_to?(:reset_hello_there)
-      end
-
       should "result in a default handle" do
-        Prop.setup :hello_there, :threshold => 4, :interval => 10
+        Prop.defaults :hello_there, :threshold => 4, :interval => 10
         4.times do |i|
-          assert_equal (i + 1), Prop.throttle_hello_there!('some key')
+          assert_equal (i + 1), Prop.throttle!(:hello_there, 'some key')
         end
 
-        assert_raises(Prop::RateLimitExceededError) { Prop.throttle_hello_there!('some key') }
-        assert_equal 5, Prop.throttle_hello_there!('some key', :threshold => 20)
+        assert_raises(Prop::RateLimitExceededError) { Prop.throttle!(:hello_there, 'some key') }
+        assert_equal 5, Prop.throttle!(:hello_there, 'some key', :threshold => 20)
       end
 
       should "create a handle accepts various cache key types" do
-        Prop.setup :hello_there, :threshold => 4, :interval => 10
-        assert_equal 1, Prop.throttle_hello_there!(5)
-        assert_equal 2, Prop.throttle_hello_there!(5)
-        assert_equal 1, Prop.throttle_hello_there!('mister')
-        assert_equal 2, Prop.throttle_hello_there!('mister')
-        assert_equal 1, Prop.throttle_hello_there!('mister', 5)
-        assert_equal 2, Prop.throttle_hello_there!('mister', 5)
-      end
-
-      should "not shadow undefined methods" do
-        assert_raises(NoMethodError) { Prop.no_such_handle }
+        Prop.defaults :hello_there, :threshold => 4, :interval => 10
+        assert_equal 1, Prop.throttle!(:hello_there, 5)
+        assert_equal 2, Prop.throttle!(:hello_there, 5)
+        assert_equal 1, Prop.throttle!(:hello_there, '6')
+        assert_equal 2, Prop.throttle!(:hello_there, '6')
+        assert_equal 1, Prop.throttle!(:hello_there, [ 5, '6' ])
+        assert_equal 2, Prop.throttle!(:hello_there, [ 5, '6' ])
       end
     end
 
     context "#reset" do
       setup do
-        Prop.setup :hello, :threshold => 10, :interval => 10
+        Prop.defaults :hello, :threshold => 10, :interval => 10
 
         5.times do |i|
-          assert_equal (i + 1), Prop.throttle_hello!
+          assert_equal (i + 1), Prop.throttle!(:hello)
         end
       end
 
       should "set the correct counter to 0" do
-        Prop.throttle_hello!('wibble')
-        Prop.throttle_hello!('wibble')
-
-        Prop.reset_hello
-        assert_equal 1, Prop.throttle_hello!
+        Prop.throttle!(:hello, 'wibble')
+        Prop.throttle!(:hello, 'wibble')
 
-        assert_equal 3, Prop.throttle_hello!('wibble')
-        Prop.reset_hello('wibble')
-        assert_equal 1, Prop.throttle_hello!('wibble')
-      end
+        Prop.reset(:hello)
+        assert_equal 1, Prop.throttle!(:hello)
 
-      should "be directly invokable" do
-        Prop.reset :key => :hello, :threshold => 10, :interval => 10
-        assert_equal 1, Prop.throttle_hello!
+        assert_equal 3, Prop.throttle!(:hello, 'wibble')
+        Prop.reset(:hello, 'wibble')
+        assert_equal 1, Prop.throttle!(:hello, 'wibble')
       end
     end
 
-    context "#throttle?" do
+    context "#throttled?" do
       should "return true once the threshold has been reached" do
-        Prop.throttle!(:key => 'hello', :threshold => 2, :interval => 10)
-        assert !Prop.throttle?(:key => 'hello', :threshold => 2, :interval => 10)
-
-        Prop.throttle!(:key => 'hello', :threshold => 2, :interval => 10)
-        assert Prop.throttle?(:key => 'hello', :threshold => 2, :interval => 10)
+        Prop.defaults(:hello, :threshold => 2, :interval => 10)
+        Prop.throttle!(:hello)
+        assert !Prop.throttled?(:hello)
+        Prop.throttle!(:hello)
+        assert Prop.throttled?(:hello)
       end
     end
 
     context "#throttle!" do
       should "increment counter correctly" do
         3.times do |i|
-          assert_equal (i + 1), Prop.throttle!(:key => 'hello', :threshold => 10, :interval => 10)
+          assert_equal (i + 1), Prop.throttle!(:hello, nil, :threshold => 10, :interval => 10)
         end
       end
 
       should "reset counter when time window is passed" do
         3.times do |i|
-          assert_equal (i + 1), Prop.throttle!(:key => 'hello', :threshold => 10, :interval => 10)
+          assert_equal (i + 1), Prop.throttle!(:hello, nil, :threshold => 10, :interval => 10)
         end
 
         Time.stubs(:now).returns(@start + 20)
 
         3.times do |i|
-          assert_equal (i + 1), Prop.throttle!(:key => 'hello', :threshold => 10, :interval => 10)
+          assert_equal (i + 1), Prop.throttle!(:hello, nil, :threshold => 10, :interval => 10)
         end
       end
 
-      should "not reset counter when violations happen during the time window for a progressive cache" do
-        start = Time.parse("2006-05-04 03:02:01")
-        Time.stubs(:now).returns(start)
-
-        Prop.setup :not_progressive, :threshold => 5, :interval => 10
-
-        assert_raises(Prop::RateLimitExceededError) do
-          6.times { Prop.throttle_not_progressive! }
-        end
-
-        Time.stubs(:now).returns(start + 5)
-        assert_raises(Prop::RateLimitExceededError) { Prop.throttle_not_progressive! }
-        Time.stubs(:now).returns(start + 15)
-        assert Prop.throttle_not_progressive!
-
-        Time.stubs(:now).returns(start)
-        Prop.setup :progressive, :threshold => 5, :interval => 10, :progressive => true
-
-        assert_raises(Prop::RateLimitExceededError) do
-          6.times { Prop.throttle_progressive! }
-        end
-
-        Time.stubs(:now).returns(start + 5)
-        assert_raises(Prop::RateLimitExceededError) { Prop.throttle_progressive! }
-
-        Time.stubs(:now).returns(start + 11)
-        assert_raises(Prop::RateLimitExceededError) { Prop.throttle_progressive! }
-      end
-
       should "not increment the counter beyond the threshold" do
+        Prop.defaults(:hello, :threshold => 5, :interval => 1)
         10.times do |i|
-          Prop.throttle!(:key => 'hello', :threshold => 5, :interval => 10) rescue nil
+          Prop.throttle!(:hello) rescue nil
         end
 
-        assert_equal 5, Prop.count(:key => 'hello', :threshold => 5, :interval => 10)
+        assert_equal 5, Prop.query(:hello)
       end
 
       should "support custom increments" do
-        Prop.throttle!(:key => 'hello', :threshold => 100, :interval => 10)
-        Prop.throttle!(:key => 'hello', :threshold => 100, :interval => 10)
+        Prop.defaults(:hello, :threshold => 100, :interval => 10)
+
+        Prop.throttle!(:hello)
+        Prop.throttle!(:hello)
 
-        assert_equal 2, Prop.count(:key => 'hello', :threshold => 100, :interval => 10)
+        assert_equal 2, Prop.query(:hello)
 
-        Prop.throttle!(:key => 'hello', :threshold => 100, :interval => 10, :increment => 48)
+        Prop.throttle!(:hello, nil, :increment => 48)
 
-        assert_equal 50, Prop.count(:key => 'hello', :threshold => 100, :interval => 10)
+        assert_equal 50, Prop.query(:hello)
       end
 
       should "raise Prop::RateLimitExceededError when the threshold is exceeded" do
         5.times do |i|
-          Prop.throttle!(:key => 'hello', :threshold => 5, :interval => 10)
+          Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
         end
         assert_raises(Prop::RateLimitExceededError) do
-          Prop.throttle!(:key => 'hello', :threshold => 5, :interval => 10)
+          Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
         end
 
         begin
-          Prop.throttle!(:key => 'hello', :threshold => 5, :interval => 10, :message => "Wibble")
+          Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
           fail
         rescue Prop::RateLimitExceededError => e
-          assert_equal "Wibble", e.message
-          assert_equal "hello threshold 5 exceeded", e.root_message
+          assert_equal :hello, e.handle
+          assert_equal "hello threshold of 5 exceeded for key ''", e.message
           assert e.retry_after
         end
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: prop
 version: !ruby/object:Gem::Version 
-  hash: 13
+  hash: 9
   prerelease: false
   segments: 
   - 0
-  - 4
+  - 5
   - 1
-  version: 0.4.1
+  version: 0.5.1
 platform: ruby
 authors: 
 - Morten Primdahl
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-08 00:00:00 -08:00
+date: 2011-02-03 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,6 +59,7 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - .document
+- .gemtest
 - LICENSE
 - README.rdoc
 - Rakefile