glebpom-prop 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Morten Primdahl
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,86 @@
+
+= Prop
+
+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.
+
+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|
+    Rails.cache.read(key)
+  end
+
+  Prop.write do |key, value|
+    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.
+
+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.defaults(:mails_per_hour, :threshold => 100, :interval => 1.hour)
+
+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)
+
+  # Returns true if the threshold/interval has been reached
+  Prop.throttled?(: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.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.:
+
+  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:
+
+  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 => 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)
+
+When the threshold are invoked without argument, the key is nil and as such a scope of its own, i.e. these are equivalent:
+
+  Prop.throttle!(:mails_per_hour)
+  Prop.throttle!(:mails_per_hour, nil)
+
+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:
+
+  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.
+
+== Copyright
+
+Copyright (c) 2010 Morten Primdahl. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "prop"
+    gem.summary = %Q{Puts a cork in their requests}
+    gem.description = %Q{A gem for implementing rate limiting}
+    gem.email = "morten@zendesk.com"
+    gem.homepage = "http://github.com/morten/prop"
+    gem.authors = ["Morten Primdahl"]
+    gem.add_development_dependency "shoulda", ">= 0"
+    gem.add_development_dependency "mocha", ">= 0.9.8"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "prop #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.1

data/lib/prop.rb

@@ -0,0 +1,116 @@
+require 'digest/md5'
+
+class Object
+  def define_prop_class_method(name, &blk)
+    (class << self; self; end).instance_eval { define_method(name, &blk) }
+  end
+end
+
+class Prop
+  class RateLimitExceededError < RuntimeError
+    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
+
+  class << self
+    attr_accessor :handles, :reader, :writer
+
+    def read(&blk)
+      self.reader = blk
+    end
+
+    def write(&blk)
+      self.writer = blk
+    end
+
+    def increment(&blk)
+      self.incrementer = blk
+    end
+
+    def incrementer=(value)
+      @incrementer = value
+    end
+
+    def incrementer
+      @incrementer ? Proc.new { |key, inc| @incrementer.call(key, inc) } :
+        Proc.new { |key, inc| self.writer.call(key, (self.reader.call(key) || 0).to_i + inc) }
+    end
+
+    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
+
+      self.handles ||= {}
+      self.handles[handle] = defaults
+    end
+
+    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
+
+      incrementer.call(cache_key, [ 1, options[:increment].to_i ].max)
+
+      if counter >= options[:threshold]
+        raise Prop::RateLimitExceededError.create(handle, normalize_cache_key(key), options[:threshold])
+      end
+    end
+
+    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 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(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(handle, key, options)
+      defaults = (handles || {})[handle] || {}
+      return {
+        :key       => normalize_cache_key(key),
+        :increment => defaults[:increment],
+        :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
+
+  end
+end

data/prop.gemspec

@@ -0,0 +1,56 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{glebpom-prop}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gleb Pomykalov"]
+  s.date = %q{2011-02-03}
+  s.description = %q{A gem for implementing rate limiting}
+  s.email = %q{gleb.pomykalov@skype.net}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".gemtest",
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/prop.rb",
+    "prop.gemspec",
+    "test/helper.rb",
+    "test/test_prop.rb"
+  ]
+  s.homepage = %q{http://github.com/glebpom/prop}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Puts a cork in their requests}
+  s.test_files = [
+    "test/helper.rb",
+    "test/test_prop.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9.8"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0.9.8"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0.9.8"])
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require 'time'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'prop'
+
+class Test::Unit::TestCase
+end

data/test/test_prop.rb

@@ -0,0 +1,152 @@
+require 'helper'
+
+class TestProp < Test::Unit::TestCase
+
+  context "Prop" do
+    setup do
+      @store = {}
+      Prop.read  { |key| @store[key] }
+      Prop.write { |key, value| @store[key] = value }
+
+      @start = Time.now
+      Time.stubs(:now).returns(@start)
+    end
+
+    {"with incrementer" => lambda { Prop.increment { |key, inc| @store[key] ? @store[key] += inc : @store[key] = inc } },
+     "without incrementer" => lambda {} }.each do |desc, setup_block_for_context|
+       context desc do
+         setup do
+           instance_eval(&setup_block_for_context)
+         end
+
+         teardown do
+           Prop.instance_variable_set("@incrementer", nil)
+         end
+
+         context "#defaults" do
+          should "raise errors on invalid configuation" do
+            assert_raises(RuntimeError) do
+              Prop.defaults :hello_there, :threshold => 20, :interval => 'hello'
+            end
+
+            assert_raises(RuntimeError) do
+              Prop.defaults :hello_there, :threshold => 'wibble', :interval => 100
+            end
+          end
+
+          should "result in a default handle" do
+            Prop.defaults :hello_there, :threshold => 4, :interval => 10
+            4.times do |i|
+              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)
+          end
+
+          should "create a handle accepts various cache key types" do
+            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.defaults :hello, :threshold => 10, :interval => 10
+
+            5.times do |i|
+              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)
+
+            assert_equal 3, Prop.throttle!(:hello, 'wibble')
+            Prop.reset(:hello, 'wibble')
+            assert_equal 1, Prop.throttle!(:hello, 'wibble')
+          end
+        end
+
+        context "#throttled?" do
+          should "return true once the threshold has been reached" do
+            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!(: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!(:hello, nil, :threshold => 10, :interval => 10)
+            end
+
+            Time.stubs(:now).returns(@start + 20)
+
+            3.times do |i|
+              assert_equal (i + 1), Prop.throttle!(:hello, nil, :threshold => 10, :interval => 10)
+            end
+          end
+
+          should "not increment the counter beyond the threshold" do
+            Prop.defaults(:hello, :threshold => 5, :interval => 1)
+            10.times do |i|
+              Prop.throttle!(:hello) rescue nil
+            end
+
+            assert_equal 5, Prop.query(:hello)
+          end
+
+          should "support custom increments" do
+            Prop.defaults(:hello, :threshold => 100, :interval => 10)
+
+            Prop.throttle!(:hello)
+            Prop.throttle!(:hello)
+
+            assert_equal 2, Prop.query(:hello)
+
+            Prop.throttle!(:hello, nil, :increment => 48)
+
+            assert_equal 50, Prop.query(:hello)
+          end
+
+          should "raise Prop::RateLimitExceededError when the threshold is exceeded" do
+            5.times do |i|
+              Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
+            end
+            assert_raises(Prop::RateLimitExceededError) do
+              Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
+            end
+
+            begin
+              Prop.throttle!(:hello, nil, :threshold => 5, :interval => 10)
+              fail
+            rescue Prop::RateLimitExceededError => e
+              assert_equal :hello, e.handle
+              assert_equal "hello threshold of 5 exceeded for key ''", e.message
+              assert e.retry_after
+            end
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: glebpom-prop
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Gleb Pomykalov
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-03 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :development
+  version_requirements: *id002
+description: A gem for implementing rate limiting
+email: gleb.pomykalov@skype.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gemtest
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/prop.rb
+- prop.gemspec
+- test/helper.rb
+- test/test_prop.rb
+homepage: http://github.com/glebpom/prop
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: Puts a cork in their requests
+test_files: 
+- test/helper.rb
+- test/test_prop.rb