prop 0.6.6 → 0.7.0

data/README.md

@@ -3,6 +3,8 @@
 
 Prop is a simple gem for rate limiting requests of any kind. It allows you to configure hooks for registering certain actions, such that you can define thresholds, register usage and finally act on exceptions once thresholds get exceeded.
 
+Prop uses and 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.
+
 To get going with Prop you first define the read and write operations. These define how you write a registered request and how to read the number of requests for a given action. For example do something like the below in a Rails initializer:
 
     Prop.read do |key|
@@ -13,7 +15,7 @@ To get going with Prop you first define the read and write operations. These def
       Rails.cache.write(key, value)
     end
 
-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.
+You can choose to rely on 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 like memcached.
 
 ## Defining thresholds
 
@@ -21,7 +23,7 @@ Once the read and write operations are defined, you can optionally define thresh
 
     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:
+The `:mails_per_hour` in the above is called the "handle". 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)
@@ -33,7 +35,7 @@ You can now put the throttle to work with this values, by passing the "handle" t
     Prop.reset(:mails_per_hour)
 
     # Returns the value of this throttle, usually a count, but see below for more
-    Prop.query(:mails_per_hour)
+    Prop.count(:mails_per_hour)
 
 Prop will raise a RuntimeError if you attempt to operate on an undefined handle.
 
@@ -52,7 +54,7 @@ The throttle scope can also be an array of values, e.g.:
 
 ## Error handling
 
-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:
+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::RateLimited error which is a subclass of StandardError. This exception contains a "handle" reference and a "description" if specified during the configuration. The handle allows you to rescue Prop::RateLimited and differentiate action depending on the handle. For example, in Rails you can use this in e.g. ApplicationController:
 
     rescue_from Prop::RateLimitExceededError do |e|
       if e.handle == :authorization_attempt
@@ -86,17 +88,3 @@ The default (and smallest possible) increment is 1, you can set that to any inte
     Prop.setup(:execute_time, :threshold => 10, :interval => 1.minute)
     Prop.throttle!(:execute_time, account.id, :increment => (Benchmark.realtime { execute }).to_i)
 
-## How it works
-
-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
-
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-

data/lib/prop.rb

@@ -1,124 +1,13 @@
-require 'digest/md5'
+require "prop/limiter"
+require "forwardable"
 
-class Object
-  def define_prop_class_method(name, &blk)
-    (class << self; self; end).instance_eval { define_method(name, &blk) }
-  end
-end
-
-class Prop
-  VERSION = "0.6.6"
-
-  class RateLimitExceededError < RuntimeError
-    attr_accessor :handle, :retry_after, :description
-
-    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
+module Prop
+  VERSION = "0.7.0"
 
+  # Short hand for accessing Prop::Limiter methods
   class << self
-    attr_accessor :handles, :reader, :writer
-
-    def read(&blk)
-      self.reader = blk
-    end
-
-    def write(&blk)
-      self.writer = blk
-    end
-
-    def configure(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
-
-      self.handles ||= {}
-      self.handles[handle] = defaults
-    end
-
-    def disabled(&block)
-      @disabled = true
-      yield
-    ensure
-      @disabled = false
-    end
-
-    def disabled?
-      !!@disabled
-    end
-
-    def throttle!(handle, key = nil, options = {})
-      options   = sanitized_prop_options(handle, key, options)
-      cache_key = sanitized_prop_key(handle, key, options)
-      counter   = reader.call(cache_key).to_i
-
-      return counter if disabled?
-
-      if counter >= 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
-    end
-
-    def throttled?(handle, key = nil, options = {})
-      options   = sanitized_prop_options(handle, key, options)
-      cache_key = sanitized_prop_key(handle, key, options)
-
-      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(handle, key, options)
-
-      writer.call(cache_key, 0)
-    end
-
-    def query(handle, key = nil, options = {})
-      options   = sanitized_prop_options(handle, key, options)
-      cache_key = sanitized_prop_key(handle, key, options)
-
-      reader.call(cache_key).to_i
-    end
-    alias :count :query
-
-    private
-
-    # Builds the expiring cache key
-    def sanitized_prop_key(handle, key, options)
-      window    = (Time.now.to_i / options[:interval])
-      cache_key = normalize_cache_key([handle, key, window])
-      "prop/#{Digest::MD5.hexdigest(cache_key)}"
-    end
-
-    # Sanitizes the option set and sets defaults
-    def sanitized_prop_options(handle, key, options)
-      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],
-        :description => defaults[:description],
-        :threshold   => defaults[:threshold].to_i,
-        :interval    => defaults[:interval].to_i
-      }.merge(options)
-    end
-
-    # Simple key expansion only supports arrays and primitives
-    def normalize_cache_key(key)
-      if key.is_a?(Array)
-        key.map { |part| normalize_cache_key(part) }.join('/')
-      else
-        key.to_s
-      end
-    end
-
+    extend Forwardable
+    def_delegators :"Prop::Limiter", :read, :write, :configure, :disabled
+    def_delegators :"Prop::Limiter", :throttle!, :throttled?, :count, :query, :reset
   end
 end

data/lib/prop/key.rb

@@ -0,0 +1,28 @@
+require "digest/md5"
+
+module Prop
+  class Key
+
+    # Builds the expiring cache key
+    def self.build(options)
+      key       = options.fetch(:key)
+      handle    = options.fetch(:handle)
+      interval  = options.fetch(:interval)
+
+      window    = (Time.now.to_i / interval)
+      cache_key = normalize([ handle, key, window ])
+
+      "prop/#{Digest::MD5.hexdigest(cache_key)}"
+    end
+
+    # Simple key expansion only supports arrays and primitives
+    def self.normalize(key)
+      if key.is_a?(Array)
+        key.flatten.join("/")
+      else
+        key.to_s
+      end
+    end
+
+  end
+end

data/lib/prop/limiter.rb

@@ -0,0 +1,116 @@
+require 'prop/rate_limited'
+require 'prop/key'
+require 'prop/options'
+
+module Prop
+  class Limiter
+
+    class << self
+      attr_accessor :handles, :reader, :writer
+
+      def read(&blk)
+        self.reader = blk
+      end
+
+      def write(&blk)
+        self.writer = blk
+      end
+
+      # Public: Registers a handle for rate limiting
+      #
+      # handle   - the name of the handle you wish to use in your code, e.g. :login_attempt
+      # defaults - the settings for this handle, e.g. { :threshold => 5, :interval => 5.minutes }
+      #
+      # Raises Prop::RateLimited if the number if the threshold for this handle has been reached
+      def configure(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
+
+        self.handles ||= {}
+        self.handles[handle] = defaults
+      end
+
+      # Public: Disables Prop for a block of code
+      #
+      # block    - a block of code within which Prop will not raise
+      def disabled(&block)
+        @disabled = true
+        yield
+      ensure
+        @disabled = false
+      end
+
+      # Public: Records a single action for the given handle/key combination.
+      #
+      # handle  - the registered handle associated with the action
+      # key     - a custom request specific key, e.g. [ account.id, "download", request.remote_ip ]
+      # options - request specific overrides to the defaults configured for this handle
+      #
+      # Raises Prop::RateLimited if the number if the threshold for this handle has been reached
+      def throttle!(handle, key = nil, options = {})
+        options, cache_key = prepare(handle, key, options)
+
+        counter = reader.call(cache_key).to_i
+
+        return counter if disabled?
+
+        if counter >= options[:threshold]
+          raise Prop::RateLimited.new(options.merge(:cache_key => cache_key, :handle => handle))
+        else
+          writer.call(cache_key, counter + [ 1, options[:increment].to_i ].max)
+        end
+      end
+
+      # Public: Allows to query whether the given handle/key combination is currently throttled
+      #
+      # handle   - the throttle identifier
+      # key      - the associated key
+      #
+      # 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)
+        reader.call(cache_key).to_i >= options[:threshold]
+      end
+
+      # Public: Resets a specific throttle
+      #
+      # handle   - the throttle identifier
+      # key      - the associated key
+      #
+      # Returns nothing
+      def reset(handle, key = nil, options = {})
+        options, cache_key = prepare(handle, key, options)
+        writer.call(cache_key, 0)
+      end
+
+      # Public: Counts the number of times the given handle/key combination has been hit in the current window
+      #
+      # handle   - the throttle identifier
+      # key      - the associated key
+      #
+      # Returns a count of hits in the current window
+      def count(handle, key = nil, options = {})
+        options, cache_key = prepare(handle, key, options)
+        reader.call(cache_key).to_i
+      end
+      alias :query :count
+
+      private
+
+      def disabled?
+        !!@disabled
+      end
+
+      def prepare(handle, key, params)
+        raise RuntimeError.new("No such handle configured: #{handle.inspect}") unless (handles || {}).key?(handle)
+
+        defaults  = handles[handle]
+        options   = Prop::Options.build(:key => key, :params => params, :defaults => defaults)
+        cache_key = Prop::Key.build(:key => key, :handle => handle, :interval => options[:interval])
+
+        [ options, cache_key ]
+      end
+
+    end
+  end
+end

data/lib/prop/middleware.rb

@@ -0,0 +1,23 @@
+module Prop
+  # Convenience middleware that conveys the message configured on a Prop handle as well
+  # as time left before the current window has passed in a Retry-After header.
+  class Middleware
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env, options = {})
+      begin
+        @app.call(env)
+      rescue Prop::RateLimited => e
+        body    = e.description || "This action has been rate limited"
+
+        headers = { "Content-Type" => "text/plain", "Content-Length" => body.size }
+        headers["Retry-After"] = e.retry_after if e.retry_after > 0
+
+        [ 429, headers, [ body ]]
+      end
+    end
+  end
+end

data/lib/prop/options.rb

@@ -0,0 +1,24 @@
+require 'prop/key'
+
+module Prop
+  class Options
+
+    # Sanitizes the option set and sets defaults
+    def self.build(options)
+      key      = options.fetch(:key)
+      params   = options.fetch(:params)
+      defaults = options.fetch(:defaults)
+      result   = defaults.merge(params)
+
+      result[:key]       = Prop::Key.normalize(key)
+      result[:threshold] = result[:threshold].to_i
+      result[:interval]  = result[:interval].to_i
+
+      raise RuntimeError.new("Invalid threshold setting") unless result[:threshold] > 0
+      raise RuntimeError.new("Invalid interval setting")  unless result[:interval] > 0
+
+      result
+    end
+
+  end
+end

data/lib/prop/rate_limited.rb

@@ -0,0 +1,19 @@
+module Prop
+  class RateLimited < StandardError
+    attr_accessor :handle, :cache_key, :retry_after, :description
+
+    def initialize(options)
+      handle    = options.fetch(:handle)
+      cache_key = options.fetch(:cache_key)
+      interval  = options.fetch(:interval).to_i
+      threshold = options.fetch(:threshold).to_i
+
+      super("#{handle} threshold of #{threshold}/#{interval}s exceeded for key '#{cache_key}'")
+
+      self.description = options[:description]
+      self.handle      = handle
+      self.cache_key   = cache_key
+      self.retry_after = interval - Time.now.to_i % interval
+    end
+  end
+end

data/prop.gemspec

@@ -13,8 +13,8 @@ Gem::Specification.new do |s|
   ## If your rubyforge_project name is different, then edit it and comment out
   ## the sub! line in the Rakefile
   s.name              = 'prop'
-  s.version           = '0.6.6'
-  s.date              = '2012-03-31'
+  s.version           = '0.7.0'
+  s.date              = '2012-04-06'
   s.rubyforge_project = 'prop'
 
   ## Make sure your summary is short. The description may be as long
@@ -66,9 +66,18 @@ Gem::Specification.new do |s|
     README.md
     Rakefile
     lib/prop.rb
+    lib/prop/key.rb
+    lib/prop/limiter.rb
+    lib/prop/middleware.rb
+    lib/prop/options.rb
+    lib/prop/rate_limited.rb
     prop.gemspec
     test/helper.rb
+    test/test_key.rb
+    test/test_middleware.rb
+    test/test_options.rb
     test/test_prop.rb
+    test/test_rate_limited.rb
   ]
   # = MANIFEST =
 

data/test/test_key.rb

@@ -0,0 +1,26 @@
+require 'helper'
+
+class TestKey < Test::Unit::TestCase
+
+  context Prop::Key do
+    context "#build" do
+      should "return a hexdigested key" do
+        assert_match /prop\/[a-f0-9]+/, Prop::Key.build(:handle => :hello, :key => [ "foo", 2, :bar ], :interval => 60)
+      end
+    end
+
+    context "#normalize" do
+      should "turn a Fixnum into a String" do
+        assert_equal "3", Prop::Key.normalize(3)
+      end
+
+      should "return a String" do
+        assert_equal "S", Prop::Key.normalize("S")
+      end
+
+      should "flatten and join an Array" do
+        assert_equal "1/B/3", Prop::Key.normalize([ 1, "B", "3" ])
+      end
+    end
+  end
+end

data/test/test_middleware.rb

@@ -0,0 +1,37 @@
+require 'helper'
+require 'prop/middleware'
+require 'prop/rate_limited'
+
+class TestMiddleware < Test::Unit::TestCase
+
+  context Prop::Middleware do
+    setup do
+      @app = stub()
+      @env = {}
+      @middleware = Prop::Middleware.new(@app)
+    end
+
+    context "when the app call completes" do
+      setup do
+        @app.expects(:call).with(@env).returns("response")
+      end
+
+      should "return the response" do
+        assert_equal "response", @middleware.call(@env)
+      end
+    end
+
+    context "when the app call results in a raised throttle" do
+      setup do
+        @app.expects(:call).with(@env).raises(Prop::RateLimited.new(:handle => "foo", :threshold => 10, :interval => 60, :cache_key => "wibble", :description => "Boom!"))
+      end
+
+      should "return the rate limited message" do
+        response = @middleware.call(@env)
+
+        assert_equal 429, response[0]
+        assert_equal ["Boom!"], response[2]
+      end
+    end
+  end
+end

data/test/test_options.rb

@@ -0,0 +1,44 @@
+require 'helper'
+
+class TestOptions < Test::Unit::TestCase
+
+  context Prop::Options do
+    context "#build" do
+      setup do
+        @args = { :key => "hello", :params => { :foo => "bif" }, :defaults => { :foo => "bar", :baz => "moo", :threshold => 10, :interval => 5 }}
+      end
+
+      context "when given valid input" do
+        setup do
+          @options = Prop::Options.build(@args)
+        end
+
+        should "support defaults" do
+          assert_equal "moo", @options[:baz]
+        end
+
+        should "override defaults" do
+          assert_equal "bif", @options[:foo]
+        end
+      end
+
+      context "when given invalid input" do
+        should "raise when not given an interval" do
+          @args[:defaults].delete(:interval)
+          assert_raises(RuntimeError) { Prop::Options.build(@args) }
+        end
+
+        should "raise when not given a threshold" do
+          @args[:defaults].delete(:threshold)
+          assert_raises(RuntimeError) { Prop::Options.build(@args) }
+        end
+
+        should "raise when not given a key" do
+          @args.delete(:key)
+          assert_raises(IndexError) { Prop::Options.build(@args) }
+        end
+      end
+    end
+
+  end
+end

data/test/test_prop.rb

@@ -29,7 +29,7 @@ class TestProp < Test::Unit::TestCase
           assert_equal (i + 1), Prop.throttle!(:hello_there, 'some key')
         end
 
-        assert_raises(Prop::RateLimitExceededError) { Prop.throttle!(:hello_there, 'some key') }
+        assert_raises(Prop::RateLimited) { Prop.throttle!(:hello_there, 'some key') }
         assert_equal 5, Prop.throttle!(:hello_there, 'some key', :threshold => 20)
       end
 
@@ -55,9 +55,9 @@ class TestProp < Test::Unit::TestCase
         Prop.disabled do
           assert_equal 2, Prop.throttle!(:hello)
           assert_equal 2, Prop.throttle!(:hello)
-          assert Prop.disabled?
+          assert Prop::Limiter.send(:disabled?)
         end
-        assert !Prop.disabled?
+        assert !Prop::Limiter.send(:disabled?)
         assert_equal 3, Prop.throttle!(:hello)
       end
     end
@@ -94,7 +94,7 @@ class TestProp < Test::Unit::TestCase
       end
     end
 
-    context "#query" do
+    context "#count" do
       setup do
         Prop.configure(:hello, :threshold => 20, :interval => 20)
         Prop.throttle!(:hello)
@@ -151,22 +151,22 @@ class TestProp < Test::Unit::TestCase
         assert_equal 50, Prop.query(:hello)
       end
 
-      should "raise Prop::RateLimitExceededError when the threshold is exceeded" do
+      should "raise Prop::RateLimited when the threshold is exceeded" do
         Prop.configure(:hello, :threshold => 5, :interval => 10, :description => "Boom!")
 
         5.times do |i|
           Prop.throttle!(:hello, nil)
         end
-        assert_raises(Prop::RateLimitExceededError) do
+        assert_raises(Prop::RateLimited) do
           Prop.throttle!(:hello, nil)
         end
 
         begin
           Prop.throttle!(:hello, nil)
           fail
-        rescue Prop::RateLimitExceededError => e
+        rescue Prop::RateLimited => e
           assert_equal :hello, e.handle
-          assert_equal "hello threshold of 5 exceeded for key ''", e.message
+          assert_match "hello threshold of 5/10s exceeded for key", e.message
           assert_equal "Boom!", e.description
           assert e.retry_after
         end

data/test/test_rate_limited.rb

@@ -0,0 +1,27 @@
+require 'helper'
+
+class TestRateLimited < Test::Unit::TestCase
+
+  context Prop::RateLimited do
+    context "#initialize" do
+      setup do
+        time = Time.at(1333685680)
+        Time.stubs(:now).returns(time)
+
+        @error = Prop::RateLimited.new(:handle => "foo", :threshold => 10, :interval => 60, :cache_key => "wibble", :description => "Boom!")
+      end
+
+      should "return an error instance" do
+        assert @error.is_a?(StandardError)
+        assert @error.is_a?(Prop::RateLimited)
+
+        assert_equal "foo", @error.handle
+        assert_equal "wibble", @error.cache_key
+        assert_equal "Boom!", @error.description
+        assert_equal "foo threshold of 10/60s exceeded for key 'wibble'", @error.message
+        assert_equal 20, @error.retry_after
+      end
+    end
+
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: prop
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 3
   prerelease: 
   segments: 
   - 0
-  - 6
-  - 6
-  version: 0.6.6
+  - 7
+  - 0
+  version: 0.7.0
 platform: ruby
 authors: 
 - Morten Primdahl
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-03-31 00:00:00 Z
+date: 2012-04-06 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rake
@@ -88,9 +88,18 @@ files:
 - README.md
 - Rakefile
 - lib/prop.rb
+- lib/prop/key.rb
+- lib/prop/limiter.rb
+- lib/prop/middleware.rb
+- lib/prop/options.rb
+- lib/prop/rate_limited.rb
 - prop.gemspec
 - test/helper.rb
+- test/test_key.rb
+- test/test_middleware.rb
+- test/test_options.rb
 - test/test_prop.rb
+- test/test_rate_limited.rb
 homepage: http://github.com/morten/prop
 licenses: []
 
@@ -125,5 +134,9 @@ signing_key:
 specification_version: 2
 summary: Gem for implementing rate limits.
 test_files: 
+- test/test_key.rb
+- test/test_middleware.rb
+- test/test_options.rb
 - test/test_prop.rb
+- test/test_rate_limited.rb
 has_rdoc: