rack-throttle 0.1.0 → 0.2.0

data/README

@@ -1,13 +1,28 @@
-HTTP Request Rate Limiter for Rack
-==================================
+HTTP Request Rate Limiter for Rack Applications
+===============================================
 
 This is [Rack][] middleware that provides logic for rate-limiting incoming
-HTTP requests to your Rack application. You can use `Rack::Throttle` with
-any Ruby web framework based on Rack, including with Ruby on Rails 3.0 and
-with Sinatra.
+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 interval (by default,
+  1 second) between subsequent HTTP requests from a particular client.
+* 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
 --------
 
@@ -23,10 +38,62 @@ Examples
 
     use Rack::Throttle::Interval, :min => 3.0
 
+### Using GDBM to store rate-limiting counters
+
+    require 'gdbm'
+    use Rack::Throttle::Interval, :cache => GDBM.new('tmp/throttle.db')
+
 ### Using Memcached to store rate-limiting counters
 
+    require 'memcached'
     use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
 
+### Using Redis to store rate-limiting counters
+
+    require 'redis'
+    use Rack::Throttle::Interval, :cache => Redis.new, :key_prefix => :throttle
+
+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 `Rack::Throttle::Interval` 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 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.
+
+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
 -------------
 
@@ -73,4 +140,11 @@ 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/
+[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/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/rack/throttle/interval.rb

@@ -29,7 +29,7 @@ module Rack; module Throttle
     def allowed?(request)
       t1 = request_start_time(request)
       t0 = cache_get(key = cache_key(request)) rescue nil
-      allowed = !t0 || (t1 - t0.to_f) >= minimum_interval
+      allowed = !t0 || (dt = t1 - t0.to_f) >= minimum_interval
       begin
         cache_set(key, t1)
         allowed
@@ -42,6 +42,15 @@ module Rack; module Throttle
       end
     end
 
+    ##
+    # Returns the number of seconds before the client is allowed to retry an
+    # HTTP request.
+    #
+    # @return [Float]
+    def retry_after
+      minimum_interval
+    end
+
     ##
     # Returns the required minimal interval (in terms of seconds) that must
     # elapse between two subsequent HTTP requests.

data/lib/rack/throttle/limiter.rb

@@ -122,7 +122,16 @@ module Rack; module Throttle
     def cache_set(key, value)
       case
         when cache.respond_to?(:[]=)
-          cache[key] = value
+          begin
+            cache[key] = value
+          rescue TypeError => e
+            # GDBM throws a "TypeError: can't convert Float into String"
+            # exception when trying to store a Float. On the other hand, we
+            # don't want to unnecessarily coerce the value to a String for
+            # any stores that do support other data types (e.g. in-memory
+            # hash objects). So, this is a compromise.
+            cache[key] = value.to_s
+          end
         when cache.respond_to?(:set)
           cache.set(key, value)
       end
@@ -164,22 +173,21 @@ module Rack; module Throttle
     ##
     # Outputs a `Rate Limit Exceeded` error.
     #
-    # @param  [Integer] code
-    # @param  [String]  message
     # @return [Array(Integer, Hash, #each)]
-    def rate_limit_exceeded(code = nil, message = nil)
-      http_error(code || options[:code] || 403,
-        message || options[:message] || 'Rate Limit Exceeded')
+    def rate_limit_exceeded
+      headers = respond_to?(:retry_after) ? {'Retry-After' => retry_after.to_f.ceil.to_s} : {}
+      http_error(options[:code] || 403, options[:message] || 'Rate Limit Exceeded', headers)
     end
 
     ##
     # Outputs an HTTP `4xx` or `5xx` response.
     #
-    # @param  [Integer]       code
-    # @param  [String, #to_s] message
+    # @param  [Integer]                code
+    # @param  [String, #to_s]          message
+    # @param  [Hash{String => String}] headers
     # @return [Array(Integer, Hash, #each)]
-    def http_error(code, message = nil)
-      [code, {'Content-Type' => 'text/plain; charset=utf-8'},
+    def http_error(code, message = nil, headers = {})
+      [code, {'Content-Type' => 'text/plain; charset=utf-8'}.merge(headers),
         http_status(code) + (message.nil? ? "\n" : " (#{message})\n")]
     end
 

data/lib/rack/throttle/version.rb

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

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Arto Bendiken
@@ -73,7 +73,7 @@ dependencies:
         version: 1.0.0
   type: :runtime
   version_requirements: *id004
-description: Rack middleware for rate-limiting HTTP requests.
+description: Rack middleware for rate-limiting incoming HTTP requests.
 email: arto.bendiken@gmail.com
 executables: []