improved-rack-throttle-w-expiry 0.8.0

data/.document

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

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+gem "rack", ">= 1.0.0"
+
+group :development, :test do
+  gem 'redis'
+  gem 'debugger'
+  gem 'timecop'
+  gem 'rack-test'
+  gem 'rspec'
+  gem 'yard' 
+  gem "simplecov", :require => false
+  gem 'redcarpet'
+  gem 'rake'
+  gem 'jeweler'
+end

data/Gemfile.lock

@@ -0,0 +1,57 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    columnize (0.3.6)
+    debugger (1.6.0)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.2.1)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.2.2)
+    diff-lcs (1.2.4)
+    git (1.2.5)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.8.0)
+    multi_json (1.7.6)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rake (10.0.4)
+    rdoc (4.0.1)
+      json (~> 1.4)
+    redcarpet (2.3.0)
+    redis (3.0.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    timecop (0.6.1)
+    yard (0.8.6.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  debugger
+  jeweler
+  rack (>= 1.0.0)
+  rack-test
+  rake
+  redcarpet
+  redis
+  rspec
+  simplecov
+  timecop
+  yard

data/README.md

@@ -0,0 +1,247 @@
+HTTP Request Rate Limiter for Rack Applications
+===============================================
+
+This is a [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.
+
+* <https://github.com/rooktone/improved-rack-throttle-w-expiry>
+
+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).
+* Scopes throttling rules by request path, http method, or user_agent
+  for applications that need a variety of rules
+* 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). This makes it easy to use global counters across
+  multiple web servers.
+* 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]
+* THE BIG DIFFERENCE: Comes with redis expiry built in. No more relying on LRU. The cache keys won't hang around forever while killing all scalability.
+
+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
+
+### Allowing 1 request per second, with bursts of up to 5 requests
+
+    use Rack::Throttle::SlidingWindow, :average => 1, :burst => 5
+
+### 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
+
+### Scoping the rate-limit to a specific path and method
+
+    use Rack::Throttle::Interval, :rules => {:url => /api/, :method => :post}
+
+Throttling Strategies
+---------------------
+
+`Rack::Throttle` supports four 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).
+* `Rack::Throttle::SlidingWindow`: Throttles the application by defining
+  an average request rate, and a burst allowance that clients can hit
+  (as long as they stay within the average). By default, this is 1
+  request per second, with bursts of up to 5 requests at a time. Users
+  who exceed the average and who have used up their burst will have all
+  of their requests denied until they comply with the policy.
+
+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.
+
+Scoping Rules
+-------------
+Rack::Throttle ships with a Rack::Throttle::Matcher base class, and three
+implementations. Rack::Throttle::UrlMatcher and
+Rack::Throttle::UserAgentMatcher allow you to pass in regular expressions
+for request path and user agent, while Rack::Throttle::MethodMatcher
+will filter by request method when passed a Symbol :get, :post, :put, or
+:delete. These rules are additive, so you can throttle just POST
+requests to your '/login' page, for example.
+
+
+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 can 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://rubydoc.info/gems/improved-rack-throttle>
+
+* {Rack::Throttle}
+  * {Rack::Throttle::Interval}
+  * {Rack::Throttle::Daily}
+  * {Rack::Throttle::Hourly}
+  * {Rack::Throttle::SlidingWindow}
+  * {Rack::Throttle::Matcher}
+  * {Rack::Throttle::MethodMatcher}
+  * {Rack::Throttle::UrlMatcher}
+  * {Rack::Throttle::UserAgentMatcher}
+
+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 improved-rack-throttle
+
+Download
+--------
+
+To get a local working copy of the development repository, do:
+
+    % git clone git://github.com/rooktone/improved-rack-throttle-w-expiry
+
+Alternatively, you can download the latest development version as a tarball
+as follows:
+
+    % wget https://github.com/rooktone/improved-rack-throttle-w-expiry/tarball/master
+
+Authors
+-------
+* [Ben Somers](mailto:somers.ben@gmail.com) - <http://www.somanyrobots.com>
+* [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
+* [Brendon Murphy](mailto:disposable.20.xternal@spamourmet.com>) - <http://www.techfreak.net/>
+* [Shane Moore](mailto:shane@ninja.ie>) - <http://ninja.ie/>
+
+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/ROADMAP.md

@@ -0,0 +1,14 @@
+## ROADMAP
+
+#### 0.7.1
+ Original fork from https://github.com/bensomers/improved-rack-throttle
+
+#### 0.8.0 +
+ The main problem with this middleware is that it doesnt scale well. Especially with redis. The keys are stored in the cache and they increase indefinitely (unless you're using an LRU mechanism).
+ This is a nightmare for scalability. So the main feature added will be the concept of an expiring key. Using redis's built in expiry mechanism will speed this up considerably.
+ Initial addition of an expiry mechanism. Only redis will be supported initially.
+ Memcache and GDBM support later.
+
+#### 0.9.0 +
+ Anyones guess
+

data/Rakefile

@@ -0,0 +1,43 @@
+# 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
+
+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
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

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"] }