rack-throttle 0.2.0 → 0.3.0

data/AUTHORS

@@ -1 +1,2 @@
 * Arto Bendiken <arto.bendiken@gmail.com>
+* Brendon Murphy <disposable.20.xternal@spamourmet.com>

data/README

@@ -11,8 +11,10 @@ Sinatra.
 Features
 --------
 
-* Throttles a Rack application by enforcing a minimum interval (by default,
-  1 second) between subsequent HTTP requests from a particular client.
+* 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
@@ -34,25 +36,65 @@ Examples
 
     run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }
 
-### Enforcing a 3-second interval between requests
+### Enforcing a minimum 3-second interval between requests
 
     use Rack::Throttle::Interval, :min => 3.0
 
-### Using GDBM to store rate-limiting counters
+### 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')
 
-### Using Memcached to store rate-limiting counters
+### Storing the rate-limiting counters on a Memcached server
 
     require 'memcached'
+    
     use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
 
-### Using Redis to store rate-limiting counters
+### 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
 --------------------------
 
@@ -62,8 +104,8 @@ 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 `Rack::Throttle::Interval` and override the
-`#client_identifier` method.
+name, you need only subclass a throttling strategy implementation and
+override the `#client_identifier` method.
 
 HTTP Response Codes and Headers
 -------------------------------
@@ -81,11 +123,11 @@ outlined in the acceptable use policy for the site, service, or API.
 
 ### 503 Service Unavailable (Rate Limit Exceeded)
 
-However, there is an unfortunately widespread practice of instead returning
-a "503 Service Unavailable" response when a client exceeds the set rate
-limits. This is actually technically incorrect 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.
+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
@@ -129,10 +171,11 @@ as follows:
 
     % wget http://github.com/datagraph/rack-throttle/tarball/master
 
-Author
-------
+Authors
+-------
 
 * [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
+* [Brendon Murphy](mailto:disposable.20.xternal@spamourmet.com>) - <http://www.techfreak.net/>
 
 License
 -------

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/rack/throttle.rb

@@ -2,10 +2,11 @@ require 'rack'
 
 module Rack
   module Throttle
-    autoload :Daily,    'rack/throttle/daily'
-    autoload :Hourly,   'rack/throttle/hourly'
-    autoload :Interval, 'rack/throttle/interval'
-    autoload :Limiter,  'rack/throttle/limiter'
-    autoload :VERSION,  'rack/throttle/version'
+    autoload :Limiter,    'rack/throttle/limiter'
+    autoload :Interval,   'rack/throttle/interval'
+    autoload :TimeWindow, 'rack/throttle/time_window'
+    autoload :Daily,      'rack/throttle/daily'
+    autoload :Hourly,     'rack/throttle/hourly'
+    autoload :VERSION,    'rack/throttle/version'
   end
 end

data/lib/rack/throttle/daily.rb

@@ -5,8 +5,40 @@ module Rack; module Throttle
   # requests per 24 hours, which works out to an average of 1 request per
   # second).
   #
-  # _Not yet implemented in the current release._
-  class Daily < Limiter
-    # TODO
+  # Note that this strategy doesn't use a sliding time window, but rather
+  # tracks requests per calendar day. This means that the throttling counter
+  # is reset at midnight (according to the server's local timezone) every
+  # night.
+  #
+  # @example Allowing up to 86,400 requests per day
+  #   use Rack::Throttle::Daily
+  #
+  # @example Allowing up to 1,000 requests per day
+  #   use Rack::Throttle::Daily, :max => 1000
+  #
+  class Daily < TimeWindow
+    ##
+    # @param  [#call]                  app
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Integer] :max   (86400)
+    def initialize(app, options = {})
+      super
+    end
+
+    ##
+    def max_per_day
+      @max_per_hour ||= options[:max_per_day] || options[:max] || 86_400
+    end
+
+    alias_method :max_per_window, :max_per_day
+
+    protected
+
+    ##
+    # @param  [Rack::Request] request
+    # @return [String]
+    def cache_key(request)
+      [super, Time.now.strftime('%Y-%m-%d')].join(':')
+    end
   end
 end; end

data/lib/rack/throttle/hourly.rb

@@ -5,8 +5,40 @@ module Rack; module Throttle
   # requests per 60 minutes, which works out to an average of 1 request per
   # second).
   #
-  # _Not yet implemented in the current release._
-  class Hourly < Limiter
-    # TODO
+  # Note that this strategy doesn't use a sliding time window, but rather
+  # tracks requests per distinct hour. This means that the throttling
+  # counter is reset every hour on the hour (according to the server's local
+  # timezone).
+  #
+  # @example Allowing up to 3,600 requests per hour
+  #   use Rack::Throttle::Hourly
+  #
+  # @example Allowing up to 100 requests per hour
+  #   use Rack::Throttle::Hourly, :max => 100
+  #
+  class Hourly < TimeWindow
+    ##
+    # @param  [#call]                  app
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Integer] :max   (3600)
+    def initialize(app, options = {})
+      super
+    end
+
+    ##
+    def max_per_hour
+      @max_per_hour ||= options[:max_per_hour] || options[:max] || 3_600
+    end
+
+    alias_method :max_per_window, :max_per_hour
+
+    protected
+
+    ##
+    # @param  [Rack::Request] request
+    # @return [String]
+    def cache_key(request)
+      [super, Time.now.strftime('%Y-%m-%dT%H')].join(':')
+    end
   end
 end; end

data/lib/rack/throttle/limiter.rb

@@ -14,8 +14,8 @@ module Rack; module Throttle
     attr_reader :options
 
     ##
-    # @param  [#call]                      app
-    # @param  [Hash{Symbol => Object}]     options
+    # @param  [#call]                       app
+    # @param  [Hash{Symbol => Object}]      options
     # @option options [String]  :cache      (Hash.new)
     # @option options [String]  :key        (nil)
     # @option options [String]  :key_prefix (nil)
@@ -85,7 +85,7 @@ module Rack; module Throttle
     ##
     # @return [Hash]
     def cache
-      case cache = (@options[:cache] ||= {})
+      case cache = (options[:cache] ||= {})
         when Proc then cache.call
         else cache
       end

data/lib/rack/throttle/time_window.rb

@@ -0,0 +1,21 @@
+module Rack; module Throttle
+  ##
+  class TimeWindow < Limiter
+    ##
+    # Returns `true` if fewer than the maximum number of requests permitted
+    # for the current window of time have been made.
+    #
+    # @param  [Rack::Request] request
+    # @return [Boolean]
+    def allowed?(request)
+      count = cache_get(key = cache_key(request)).to_i + 1 rescue 1
+      allowed = count <= max_per_window
+      begin
+        cache_set(key, count)
+        allowed
+      rescue => e
+        allowed = true
+      end
+    end
+  end
+end; end

data/lib/rack/throttle/version.rb

@@ -1,7 +1,7 @@
 module Rack; module Throttle
   module VERSION
     MAJOR = 0
-    MINOR = 2
+    MINOR = 3
     TINY  = 0
     EXTRA = nil
 

metadata

@@ -4,17 +4,18 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Arto Bendiken
+- Brendon Murphy
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-03-21 00:00:00 +01:00
+date: 2010-03-22 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -90,6 +91,7 @@ files:
 - lib/rack/throttle/hourly.rb
 - lib/rack/throttle/interval.rb
 - lib/rack/throttle/limiter.rb
+- lib/rack/throttle/time_window.rb
 - lib/rack/throttle/version.rb
 - lib/rack/throttle.rb
 has_rdoc: false
@@ -123,6 +125,6 @@ rubyforge_project: datagraph
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: Rate limiter for Rack.
+summary: HTTP request rate limiter for Rack applications.
 test_files: []