improved-rack-throttle 0.5.0

data/.document

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

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+gem "rack", "~> 1.0.0"
+
+group :development, :test do
+  gem 'timecop',   '~> 0.5.2'
+  gem 'rack-test', '~> 0.6.2'
+  gem 'rspec',     '~> 2.11.0'
+  gem 'yard' ,     '>= 0.5.5'
+  gem 'rake'
+  gem 'jeweler'
+end

data/Gemfile.lock

@@ -0,0 +1,39 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.5)
+    rack (1.0.1)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+    timecop (0.5.2)
+    yard (0.8.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  rack (~> 1.0.0)
+  rack-test (~> 0.6.2)
+  rake
+  rspec (~> 2.11.0)
+  timecop (~> 0.5.2)
+  yard (>= 0.5.5)

data/README.md

@@ -0,0 +1,213 @@
+HTTP Request Rate Limiter for Rack Applications
+===============================================
+
+This is [Rack][] middleware that provides logic for rate-limiting incoming
+HTTP requests to Rack applications. You can use `Rack::Throttle` with any
+Ruby web framework based on Rack, including with Ruby on Rails 3.0 and with
+Sinatra.
+
+* <http://github.com/datagraph/rack-throttle>
+
+Features
+--------
+
+* Throttles a Rack application by enforcing a minimum time interval between
+  subsequent HTTP requests from a particular client, as well as by defining
+  a maximum number of allowed HTTP requests per a given time period (hourly
+  or daily).
+* Compatible with any Rack application and any Rack-based framework.
+* Stores rate-limiting counters in any key/value store implementation that
+  responds to `#[]`/`#[]=` (like Ruby's hashes) or to `#get`/`#set` (like
+  memcached or Redis).
+* Compatible with the [gdbm][] binding included in Ruby's standard library.
+* Compatible with the [memcached][], [memcache-client][], [memcache][] and
+  [redis][] gems.
+* Compatible with [Heroku][]'s [memcached add-on][Heroku memcache]
+  (currently available as a free beta service).
+
+Examples
+--------
+
+### Adding throttling to a Rails 3.x application
+
+    # config/application.rb
+    require 'rack/throttle'
+    
+    class Application < Rails::Application
+      config.middleware.use Rack::Throttle::Interval
+    end
+
+### Adding throttling to a Sinatra application
+
+    #!/usr/bin/env ruby -rubygems
+    require 'sinatra'
+    require 'rack/throttle'
+    
+    use Rack::Throttle::Interval
+    
+    get('/hello') { "Hello, world!\n" }
+
+### Adding throttling to a Rackup application
+
+    #!/usr/bin/env rackup
+    require 'rack/throttle'
+    
+    use Rack::Throttle::Interval
+    
+    run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }
+
+### Enforcing a minimum 3-second interval between requests
+
+    use Rack::Throttle::Interval, :min => 3.0
+
+### Allowing a maximum of 100 requests per hour
+
+    use Rack::Throttle::Hourly,   :max => 100
+
+### Allowing a maximum of 1,000 requests per day
+
+    use Rack::Throttle::Daily,    :max => 1000
+
+### Combining various throttling constraints into one overall policy
+
+    use Rack::Throttle::Daily,    :max => 1000  # requests
+    use Rack::Throttle::Hourly,   :max => 100   # requests
+    use Rack::Throttle::Interval, :min => 3.0   # seconds
+
+### Storing the rate-limiting counters in a GDBM database
+
+    require 'gdbm'
+    
+    use Rack::Throttle::Interval, :cache => GDBM.new('tmp/throttle.db')
+
+### Storing the rate-limiting counters on a Memcached server
+
+    require 'memcached'
+    
+    use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
+
+### Storing the rate-limiting counters on a Redis server
+
+    require 'redis'
+    
+    use Rack::Throttle::Interval, :cache => Redis.new, :key_prefix => :throttle
+
+Throttling Strategies
+---------------------
+
+`Rack::Throttle` supports three built-in throttling strategies:
+
+* `Rack::Throttle::Interval`: Throttles the application by enforcing a
+  minimum interval (by default, 1 second) between subsequent HTTP requests.
+* `Rack::Throttle::Hourly`: Throttles the application by defining a
+  maximum number of allowed HTTP requests per hour (by default, 3,600
+  requests per 60 minutes, which works out to an average of 1 request per
+  second).
+* `Rack::Throttle::Daily`: Throttles the application by defining a
+  maximum number of allowed HTTP requests per day (by default, 86,400
+  requests per 24 hours, which works out to an average of 1 request per
+  second).
+
+You can fully customize the implementation details of any of these strategies
+by simply subclassing one of the aforementioned default implementations.
+And, of course, should your application-specific requirements be
+significantly more complex than what we've provided for, you can also define
+entirely new kinds of throttling strategies by subclassing the
+`Rack::Throttle::Limiter` base class directly.
+
+HTTP Client Identification
+--------------------------
+
+The rate-limiting counters stored and maintained by `Rack::Throttle` are
+keyed to unique HTTP clients.
+
+By default, HTTP clients are uniquely identified by their IP address as
+returned by `Rack::Request#ip`. If you wish to instead use a more granular,
+application-specific identifier such as a session key or a user account
+name, you need only subclass a throttling strategy implementation and
+override the `#client_identifier` method.
+
+HTTP Response Codes and Headers
+-------------------------------
+
+### 403 Forbidden (Rate Limit Exceeded)
+
+When a client exceeds their rate limit, `Rack::Throttle` by default returns
+a "403 Forbidden" response with an associated "Rate Limit Exceeded" message
+in the response body.
+
+An HTTP 403 response means that the server understood the request, but is
+refusing to respond to it and an accompanying message will explain why.
+This indicates an error on the client's part in exceeding the rate limits
+outlined in the acceptable use policy for the site, service, or API.
+
+### 503 Service Unavailable (Rate Limit Exceeded)
+
+However, there exists a widespread practice of instead returning a "503
+Service Unavailable" response when a client exceeds the set rate limits.
+This is technically dubious because it indicates an error on the server's
+part, which is certainly not the case with rate limiting - it was the client
+that committed the oops, not the server.
+
+An HTTP 503 response would be correct in situations where the server was
+genuinely overloaded and couldn't handle more requests, but for rate
+limiting an HTTP 403 response is more appropriate. Nonetheless, if you think
+otherwise, `Rack::Throttle` does allow you to override the returned HTTP
+status code by passing in a `:code => 503` option when constructing a
+`Rack::Throttle::Limiter` instance.
+
+Documentation
+-------------
+
+<http://datagraph.rubyforge.org/rack-throttle/>
+
+* {Rack::Throttle}
+  * {Rack::Throttle::Interval}
+  * {Rack::Throttle::Daily}
+  * {Rack::Throttle::Hourly}
+
+Dependencies
+------------
+
+* [Rack](http://rubygems.org/gems/rack) (>= 1.0.0)
+
+Installation
+------------
+
+The recommended installation method is via [RubyGems](http://rubygems.org/).
+To install the latest official release of the gem, do:
+
+    % [sudo] gem install rack-throttle
+
+Download
+--------
+
+To get a local working copy of the development repository, do:
+
+    % git clone git://github.com/datagraph/rack-throttle.git
+
+Alternatively, you can download the latest development version as a tarball
+as follows:
+
+    % wget http://github.com/datagraph/rack-throttle/tarball/master
+
+Authors
+-------
+
+* [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
+* [Brendon Murphy](mailto:disposable.20.xternal@spamourmet.com>) - <http://www.techfreak.net/>
+
+License
+-------
+
+`Rack::Throttle` is free and unencumbered public domain software. For more
+information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
+
+[Rack]:            http://rack.rubyforge.org/
+[gdbm]:            http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html
+[memcached]:       http://rubygems.org/gems/memcached
+[memcache-client]: http://rubygems.org/gems/memcache-client
+[memcache]:        http://rubygems.org/gems/memcache
+[redis]:           http://rubygems.org/gems/redis
+[Heroku]:          http://heroku.com/
+[Heroku memcache]: http://docs.heroku.com/memcache

data/Rakefile

@@ -0,0 +1,41 @@
+# encoding: utf-8
+$:.push File.join(File.dirname(__FILE__),'lib')
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'rack/throttle'
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "improved-rack-throttle"
+  gem.version = Rack::Throttle::VERSION
+  gem.homepage = "http://github.com/bensomers/improved-rack-throttle"
+  gem.license = "Public Domain"
+  gem.summary = %Q{HTTP request rate limiter for Rack applications.}
+  gem.description = %Q{Rack middleware for rate-limiting incoming HTTP requests.}
+  gem.email = "somers.ben@gmail.com"
+  gem.authors = ["Ben Somers", "Arto Bendiken", "Brendon Murphy"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "improved-rack-throttle #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

data/doc/.gitignore

@@ -0,0 +1,2 @@
+rdoc
+yard

data/etc/gdbm.ru

@@ -0,0 +1,7 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rack/throttle'
+require 'gdbm'
+
+use Rack::Throttle::Interval, :min => 3.0, :cache => GDBM.new('/tmp/throttle.db')
+
+run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }

data/etc/hash.ru

@@ -0,0 +1,6 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rack/throttle'
+
+use Rack::Throttle::Interval, :min => 3.0, :cache => {}
+
+run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }

data/etc/memcache-client.ru

@@ -0,0 +1,8 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rack/throttle'
+gem 'memcache-client'
+require 'memcache'
+
+use Rack::Throttle::Interval, :min => 3.0, :cache => MemCache.new('localhost:11211')
+
+run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }

data/etc/memcache.ru

@@ -0,0 +1,8 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rack/throttle'
+gem 'memcache'
+require 'memcache'
+
+use Rack::Throttle::Interval, :min => 3.0, :cache => Memcache.new(:server => 'localhost:11211')
+
+run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }

data/etc/memcached.ru

@@ -0,0 +1,8 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rack/throttle'
+gem 'memcached'
+require 'memcached'
+
+use Rack::Throttle::Interval, :min => 3.0, :cache => Memcached.new
+
+run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }

data/etc/redis.ru

@@ -0,0 +1,8 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rack/throttle'
+gem 'redis'
+require 'redis'
+
+use Rack::Throttle::Interval, :min => 3.0, :cache => Redis.new
+
+run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }

data/improved-rack-throttle.gemspec

@@ -0,0 +1,85 @@
+# 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 = "improved-rack-throttle"
+  s.version = "0.5.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ben Somers", "Arto Bendiken", "Brendon Murphy"]
+  s.date = "2012-10-03"
+  s.description = "Rack middleware for rate-limiting incoming HTTP requests."
+  s.email = "somers.ben@gmail.com"
+  s.extra_rdoc_files = [
+    "UNLICENSE",
+    "README.md"
+  ]
+  s.files = [
+    "README.md",
+    "Rakefile",
+    "UNLICENSE",
+    "doc/.gitignore",
+    "etc/gdbm.ru",
+    "etc/hash.ru",
+    "etc/memcache-client.ru",
+    "etc/memcache.ru",
+    "etc/memcached.ru",
+    "etc/redis.ru",
+    "lib/rack/throttle.rb",
+    "lib/rack/throttle/daily.rb",
+    "lib/rack/throttle/hourly.rb",
+    "lib/rack/throttle/interval.rb",
+    "lib/rack/throttle/limiter.rb",
+    "lib/rack/throttle/matcher.rb",
+    "lib/rack/throttle/matchers/ip_matcher.rb",
+    "lib/rack/throttle/matchers/method_matcher.rb",
+    "lib/rack/throttle/matchers/url_matcher.rb",
+    "lib/rack/throttle/time_window.rb",
+    "lib/rack/throttle/version.rb",
+    "spec/daily_spec.rb",
+    "spec/hourly_spec.rb",
+    "spec/interval_spec.rb",
+    "spec/limiter_spec.rb",
+    "spec/method_matcher_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/url_matcher_spec.rb"
+  ]
+  s.homepage = "http://github.com/bensomers/improved-rack-throttle"
+  s.licenses = ["Public Domain"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.17"
+  s.summary = "HTTP request rate limiter for Rack applications."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rack>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<timecop>, ["~> 0.5.2"])
+      s.add_development_dependency(%q<rack-test>, ["~> 0.6.2"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.11.0"])
+      s.add_development_dependency(%q<yard>, [">= 0.5.5"])
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<rack>, ["~> 1.0.0"])
+      s.add_dependency(%q<timecop>, ["~> 0.5.2"])
+      s.add_dependency(%q<rack-test>, ["~> 0.6.2"])
+      s.add_dependency(%q<rspec>, ["~> 2.11.0"])
+      s.add_dependency(%q<yard>, [">= 0.5.5"])
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rack>, ["~> 1.0.0"])
+    s.add_dependency(%q<timecop>, ["~> 0.5.2"])
+    s.add_dependency(%q<rack-test>, ["~> 0.6.2"])
+    s.add_dependency(%q<rspec>, ["~> 2.11.0"])
+    s.add_dependency(%q<yard>, [">= 0.5.5"])
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+