prop 0.6.1 → 0.6.2

data/README.rdoc

@@ -15,9 +15,11 @@ To get going with Prop you first define the read and write operations. These def
 
 You can choose to rely on a database or Moneta or Redis or whatever you'd like to use for transient storage. Prop does not do any sort of clean up of its key space, so you would have to implement that manually should you be using anything but an LRU cache.
 
+== Defining thresholds
+
 Once the read and write operations are defined, you can optionally define 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.configure(:mails_per_hour, :threshold => 100, :interval => 1.hour)
+  Prop.configure(:mails_per_hour, :threshold => 100, :interval => 1.hour, :description => "Mail rate limit exceeded")
 
 You can now put the throttle to work with this values, by passing the "handle" to the respective methods in Prop:
 
@@ -33,6 +35,10 @@ You can now put the throttle to work with this values, by passing the "handle" t
   # Returns the value of this throttle, usually a count, but see below for more
   Prop.query(:mails_per_hour)
 
+Prop will raise a RuntimeError if you attempt to operate on an undefined handle.
+
+== Scoping a throttle
+
 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)
@@ -44,18 +50,31 @@ The throttle scope can also be an array of values, e.g.:
 
   Prop.throttle!(:mails_per_hour, [ account.id, mail.from ])
 
-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:
+== Error handling
 
-  THROTTLE_MESSAGES = Hash.new("Throttle exceeded")
-  THROTTLE_MESSAGES[:login] = "Too many invalid login attempts. Try again later."
+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 and a "description" if specified during the configuration. The handle allows you to rescue Prop::RateLimitExceededError and differentiate action depending on the handle. For example, in Rails you can use this in e.g. ApplicationController:
 
-  rescue_from Prop::RateLimitExceededError do |exception|
-    render :status => 403, :message => I18n.t(THROTTLE_MESSAGES[exception.handle])
+  rescue_from Prop::RateLimitExceededError do |e|
+    if e.handle == :authorization_attempt
+      render :status => :forbidden, :message => I18n.t(e.description)
+    elsif ...
+
+    end
   end
 
+== Disabling Prop
+
+In case you need to perform e.g. a manual bulk operation:
+
+  Prop.disabled do
+    # No throttles will be tested here
+  end
+
+== Threshold settings
+
 You can chose to override the threshold for a given key:
 
-  Prop.throttle!(:mails_per_hour, mail.from, :threshold => account.mail_throttle_threshold)
+  Prop.throttle!(:mails_per_hour, mail.from, :threshold => current_account.mail_throttle_threshold)
 
 When the threshold are invoked without argument, the key is nil and as such a scope of its own, i.e. these are equivalent:
 

data/VERSION

@@ -1 +1 @@
-0.6.1
+0.6.2

data/lib/prop.rb

@@ -8,12 +8,14 @@ end
 
 class Prop
   class RateLimitExceededError < RuntimeError
-    attr_accessor :handle, :retry_after
+    attr_accessor :handle, :retry_after, :description
 
-    def self.create(handle, key, threshold)
+    def self.create(handle, key, threshold, description = nil)
       error = new("#{handle} threshold of #{threshold} exceeded for key '#{key}'")
+      error.description = description
       error.handle      = handle
       error.retry_after = threshold - Time.now.to_i % threshold if threshold > 0
+
       raise error
     end
   end
@@ -56,7 +58,7 @@ class Prop
       return counter if disabled?
 
       if counter >= options[:threshold]
-        raise Prop::RateLimitExceededError.create(handle, normalize_cache_key(key), options[:threshold])
+        raise Prop::RateLimitExceededError.create(handle, normalize_cache_key(key), options[:threshold], options[:description])
       else
         writer.call(cache_key, counter + [ 1, options[:increment].to_i ].max)
       end
@@ -94,7 +96,9 @@ class Prop
 
     # Sanitizes the option set and sets defaults
     def sanitized_prop_options(handle, key, options)
-      defaults = (handles || {})[handle] || {}
+      raise RuntimeError.new("No such handle configured: #{handle.inspect}") if handles.nil? || handles[handle].nil?
+
+      defaults = handles[handle]
       return {
         :key       => normalize_cache_key(key),
         :increment => defaults[:increment],

data/prop.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{prop}
-  s.version = "0.6.1"
+  s.version = "0.6.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Morten Primdahl"]
-  s.date = %q{2011-08-18}
+  s.date = %q{2011-08-22}
   s.description = %q{A gem for implementing rate limiting}
   s.email = %q{morten@zendesk.com}
   s.extra_rdoc_files = [

data/test/test_prop.rb

@@ -144,14 +144,21 @@ class TestProp < Test::Unit::TestCase
         end
 
         begin
-          Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
+          Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10, :description => "Boom!")
           fail
         rescue Prop::RateLimitExceededError => e
           assert_equal :hello, e.handle
           assert_equal "hello threshold of 5 exceeded for key ''", e.message
+          assert_equal "Boom!", e.description
           assert e.retry_after
         end
       end
+
+      should "raise a RuntimeError when a handle has not been configured" do
+        assert_raises(RuntimeError) do
+          Prop.throttle!(:no_such_handle, nil, :threshold => 5, :interval => 10)
+        end
+      end
     end
 
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: prop
 version: !ruby/object:Gem::Version 
-  hash: 5
+  hash: 3
   prerelease: 
   segments: 
   - 0
   - 6
-  - 1
-  version: 0.6.1
+  - 2
+  version: 0.6.2
 platform: ruby
 authors: 
 - Morten Primdahl
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-18 00:00:00 -07:00
+date: 2011-08-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency