improved-rack-throttle 0.7.0 → 0.7.1

data/Gemfile

@@ -7,6 +7,7 @@ group :development, :test do
   gem 'rack-test', '~> 0.6.2'
   gem 'rspec',     '~> 2.11.0'
   gem 'yard' ,     '>= 0.5.5'
+  gem 'redcarpet'
   gem 'rake'
   gem 'jeweler'
 end

data/Gemfile.lock

@@ -8,13 +8,14 @@ GEM
       git (>= 1.2.5)
       rake
       rdoc
-    json (1.7.5)
-    rack (1.4.1)
+    json (1.7.6)
+    rack (1.4.4)
     rack-test (0.6.2)
       rack (>= 1.0)
-    rake (0.9.2.2)
+    rake (10.0.3)
     rdoc (3.12)
       json (~> 1.4)
+    redcarpet (2.2.2)
     rspec (2.11.0)
       rspec-core (~> 2.11.0)
       rspec-expectations (~> 2.11.0)
@@ -23,8 +24,8 @@ GEM
     rspec-expectations (2.11.3)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.11.3)
-    timecop (0.5.2)
-    yard (0.8.2.1)
+    timecop (0.5.9.1)
+    yard (0.8.3)
 
 PLATFORMS
   ruby
@@ -34,6 +35,7 @@ DEPENDENCIES
   rack (>= 1.0.0)
   rack-test (~> 0.6.2)
   rake
+  redcarpet
   rspec (~> 2.11.0)
   timecop (~> 0.5.2)
   yard (>= 0.5.5)

data/README.md

@@ -1,12 +1,15 @@
 HTTP Request Rate Limiter for Rack Applications
 ===============================================
 
-This is [Rack][] middleware that provides logic for rate-limiting incoming
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/bensomers/improved-rack-throttle)
+[![Dependency Status](https://gemnasium.com/bensomers/improved-rack-throttle.png)](https://gemnasium.com/bensomers/improved-rack-throttle)
+
+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.
 
-* <http://github.com/datagraph/rack-throttle>
+* <http://github.com/bensomers/improved-rack-throttle>
 
 Features
 --------
@@ -26,7 +29,6 @@ Features
 * 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
 --------
@@ -71,6 +73,10 @@ Examples
 
     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
@@ -102,7 +108,7 @@ Examples
 Throttling Strategies
 ---------------------
 
-`Rack::Throttle` supports three built-in 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.
@@ -114,6 +120,12 @@ Throttling Strategies
   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.
@@ -125,7 +137,7 @@ entirely new kinds of throttling strategies by subclassing the
 Scoping Rules
 -------------
 Rack::Throttle ships with a Rack::Throttle::Matcher base class, and three
-implementations of it. Rack::Throttle::UrlMatcher and
+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
@@ -142,7 +154,7 @@ 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
+name, you can subclass a throttling strategy implementation and
 override the `#client_identifier` method.
 
 HTTP Response Codes and Headers
@@ -176,14 +188,19 @@ status code by passing in a `:code => 503` option when constructing a
 
 Documentation
 -------------
-OUT OF DATE
+UNDER DEVELOPMENT
 
-<http://datagraph.rubyforge.org/rack-throttle/>
+<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
 ------------

data/improved-rack-throttle.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "improved-rack-throttle"
-  s.version = "0.7.0"
+  s.version = "0.7.1"
 
   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-05"
+  s.date = "2013-05-09"
   s.description = "Rack middleware for rate-limiting incoming HTTP requests."
   s.email = "somers.ben@gmail.com"
   s.extra_rdoc_files = [
@@ -55,7 +55,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/bensomers/improved-rack-throttle"
   s.licenses = ["Public Domain"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.17"
+  s.rubygems_version = "1.8.25"
   s.summary = "HTTP request rate limiter for Rack applications."
 
   if s.respond_to? :specification_version then
@@ -67,6 +67,7 @@ Gem::Specification.new do |s|
       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<redcarpet>, [">= 0"])
       s.add_development_dependency(%q<rake>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, [">= 0"])
     else
@@ -75,6 +76,7 @@ Gem::Specification.new do |s|
       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<redcarpet>, [">= 0"])
       s.add_dependency(%q<rake>, [">= 0"])
       s.add_dependency(%q<jeweler>, [">= 0"])
     end
@@ -84,6 +86,7 @@ Gem::Specification.new do |s|
     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<redcarpet>, [">= 0"])
     s.add_dependency(%q<rake>, [">= 0"])
     s.add_dependency(%q<jeweler>, [">= 0"])
   end

data/lib/rack/throttle/limiters/sliding_window.rb

@@ -18,9 +18,8 @@ module Rack; module Throttle
     end
 
     ##
-    # Returns `true` if sufficient time (equal to or more than
-    # {#minimum_interval}) has passed since the last request and the given
-    # present `request`.
+    # Returns `true` if the request conforms to the 
+    # specified :average and :burst rules
     #
     # @param  [Rack::Request] request
     # @return [Boolean]
@@ -45,10 +44,18 @@ module Rack; module Throttle
       end
     end
 
+    ###
+    # LeakyBucket is an internal class used to implement the
+    # SlidingWindow limiter strategy. It is a (slightly tweaked)
+    # implementation of the {http://en.wikipedia.org/wiki/Leaky_bucket
+    # Leaky Bucket Algorithm}.
     class LeakyBucket
       attr_accessor :maximum, :outflow
       attr_reader :count, :last_touched
 
+      ##
+      # @param [Integer] maximum
+      # @param [Float] outflow
       def initialize(maximum, outflow)
         @maximum, @outflow = maximum, outflow
         @count, @last_touched = 0, Time.now

data/lib/rack/throttle/matchers/matcher.rb

@@ -1,9 +1,9 @@
 module Rack; module Throttle
   ###
-  # This is the base class for matcher implementations
-  # Implements IP, user agent, url, and request method based matching
-  # e.g. implement throttling rules that discriminate by ip, user agent, url, request method,
-  # or any combination thereof
+  # This is the base class for matcher implementations.
+  # Implementations are provided for User Agent, URL, and request
+  # method. Subclass Matcher if you want to provide a custom
+  # implementation.
   class Matcher
     attr_reader :rule
 
@@ -11,11 +11,19 @@ module Rack; module Throttle
       @rule = rule
     end
 
-    # MUST return true or false
+    # Must be implemented in a subclass.
+    # MUST return true or false.
+    # @return [Boolean]
+    # @abstract
     def match?
       true
     end
 
+    # Must be implemented in a subclass.
+    # Used to produce a unique key in our cache store.
+    # Typically of the form "xx-"
+    # @return [String]
+    # @abstract
     def identifier
       ""
     end

data/lib/rack/throttle/matchers/method_matcher.rb

@@ -1,12 +1,21 @@
 module Rack; module Throttle
   ###
+  # MethodMatchers are used to restrict throttling based on the HTTP
+  # method used by the request. For instance, you may only care about
+  # throttling POST requests on a login form; GET requests are just
+  # fine.
   # MethodMatchers take Symbol objects of :get, :put, :post, or :delete
   class MethodMatcher < Matcher
+    ##
+    # @param [Rack::Request] request
+    # @return [Boolean]
     def match?(request)
       rack_method = :"#{@rule}?"
       request.send(rack_method)
     end
 
+    ##
+    # @return [String]
     def identifier
       "meth-#{@rule}"
     end

data/lib/rack/throttle/matchers/url_matcher.rb

@@ -1,11 +1,20 @@
 module Rack; module Throttle
   ###
-  # UrlMatchers take Regexp objects and compare the request path against them
+  # UrlMatchers are used to restrict requests based on the URL
+  # requested. For instance, you may care about limiting requests
+  # to a machine-consumed API, but not be concerned about requests
+  # coming from browsers.
+  # UrlMatchers take Regexp object to matcha gainst the request path.
   class UrlMatcher < Matcher
+    ###
+    # @param [Rack::Request] request
+    # @return [Boolean]
     def match?(request)
       !!(@rule =~ request.path)
     end
 
+    ###
+    # @return [String]
     def identifier
       "url-" + @rule.inspect
     end

data/lib/rack/throttle/matchers/user_agent_matcher.rb

@@ -1,11 +1,20 @@
 module Rack; module Throttle
   ###
-  # IpMatchers take RegExp objects and compare the request ip against them
+  # User Agent Matchers are used to restrict requests based on the User
+  # Agent supplied by the requester. For instance, you may care about
+  # limiting a specific API consumer who reliably uses a known User-Agent.
+  # UserAgentMatchers take Regexp objects to match against the
+  # User-Agent.
   class UserAgentMatcher < Matcher
+    ###
+    # @param [Rack::Request] request
+    # @return [Boolean]
     def match?(request)
       !!(@rule =~ request.user_agent)
     end
 
+    ###
+    # @return [String]
     def identifier
       "ua-" + @rule.inspect
     end

data/lib/rack/throttle/version.rb

@@ -2,7 +2,7 @@ module Rack; module Throttle
   module VERSION
     MAJOR = 0
     MINOR = 7
-    TINY  = 0
+    TINY  = 1
     EXTRA = nil
 
     STRING = [MAJOR, MINOR, TINY].join('.')

data/spec/limiters/sliding_window_spec.rb

@@ -9,8 +9,8 @@ describe Rack::Throttle::SlidingWindow do
   end
 
   before(:each) do
-    @time = Time.now
     Timecop.freeze
+    @time = Time.now
   end
 
   after(:each) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: improved-rack-throttle
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-05 00:00:00.000000000 Z
+date: 2013-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70296124961520 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,15 @@ dependencies:
         version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *70296124961520
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: timecop
-  requirement: &70296124960800 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -34,10 +39,15 @@ dependencies:
         version: 0.5.2
   type: :development
   prerelease: false
-  version_requirements: *70296124960800
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.5.2
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &70296124960000 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -45,10 +55,15 @@ dependencies:
         version: 0.6.2
   type: :development
   prerelease: false
-  version_requirements: *70296124960000
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.2
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70296124959520 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -56,21 +71,47 @@ dependencies:
         version: 2.11.0
   type: :development
   prerelease: false
-  version_requirements: *70296124959520
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70296124958980 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 0.5.5
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70296124958980
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70296124958220 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -78,10 +119,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70296124958220
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70296124957640 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -89,7 +135,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70296124957640
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Rack middleware for rate-limiting incoming HTTP requests.
 email: somers.ben@gmail.com
 executables: []
@@ -147,7 +198,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3964473901145440251
+      hash: -4496223408765979053
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -156,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: HTTP request rate limiter for Rack applications.