rack-throttle 0.0.0 → 0.1.0

data/README

@@ -0,0 +1,76 @@
+HTTP Request Rate Limiter for Rack
+==================================
+
+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://github.com/datagraph/rack-throttle>
+
+Examples
+--------
+
+### Adding throttling to a Rackup application
+
+    require 'rack/throttle'
+
+    use Rack::Throttle::Interval
+
+    run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }
+
+### Enforcing a 3-second interval between requests
+
+    use Rack::Throttle::Interval, :min => 3.0
+
+### Using Memcached to store rate-limiting counters
+
+    use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
+
+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. To install the latest
+official release, 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
+
+Author
+------
+
+* [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
+
+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/

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/lib/rack/throttle.rb

@@ -2,6 +2,10 @@ require 'rack'
 
 module Rack
   module Throttle
-    autoload :VERSION, 'rack/throttle/version'
+    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'
   end
 end

data/lib/rack/throttle/daily.rb

@@ -0,0 +1,12 @@
+module Rack; module Throttle
+  ##
+  # This rate limiter strategy 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).
+  #
+  # _Not yet implemented in the current release._
+  class Daily < Limiter
+    # TODO
+  end
+end; end

data/lib/rack/throttle/hourly.rb

@@ -0,0 +1,12 @@
+module Rack; module Throttle
+  ##
+  # This rate limiter strategy 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).
+  #
+  # _Not yet implemented in the current release._
+  class Hourly < Limiter
+    # TODO
+  end
+end; end

data/lib/rack/throttle/interval.rb

@@ -0,0 +1,54 @@
+module Rack; module Throttle
+  ##
+  # This rate limiter strategy throttles the application by enforcing a
+  # minimum interval (by default, 1 second) between subsequent allowed HTTP
+  # requests.
+  #
+  # @example Allowing up to two requests per second
+  #   use Rack::Throttle::Interval, :min => 0.5   #  500 ms interval
+  #
+  # @example Allowing a request every two seconds
+  #   use Rack::Throttle::Interval, :min => 2.0   # 2000 ms interval
+  #
+  class Interval < Limiter
+    ##
+    # @param  [#call]                  app
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Float] :min     (1.0)
+    def initialize(app, options = {})
+      super
+    end
+
+    ##
+    # Returns `true` if sufficient time (equal to or more than
+    # {#minimum_interval}) has passed since the last request and the given
+    # present `request`.
+    #
+    # @param  [Rack::Request] request
+    # @return [Boolean]
+    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
+      begin
+        cache_set(key, t1)
+        allowed
+      rescue => e
+        # If an error occurred while trying to update the timestamp stored
+        # in the cache, we will fall back to allowing the request through.
+        # This prevents the Rack application blowing up merely due to a
+        # backend cache server (Memcached, Redis, etc.) being offline.
+        allowed = true
+      end
+    end
+
+    ##
+    # Returns the required minimal interval (in terms of seconds) that must
+    # elapse between two subsequent HTTP requests.
+    #
+    # @return [Float]
+    def minimum_interval
+      @min ||= (@options[:min] || 1.0).to_f
+    end
+  end
+end; end

data/lib/rack/throttle/limiter.rb

@@ -0,0 +1,195 @@
+module Rack; module Throttle
+  ##
+  # This is the base class for rate limiter implementations.
+  #
+  # @example Defining a rate limiter subclass
+  #   class MyLimiter < Limiter
+  #     def allowed?(request)
+  #       # TODO: custom logic goes here
+  #     end
+  #   end
+  #
+  class Limiter
+    attr_reader :app
+    attr_reader :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)
+    # @option options [Integer] :code       (403)
+    # @option options [String]  :message    ("Rate Limit Exceeded")
+    def initialize(app, options = {})
+      @app, @options = app, options
+    end
+
+    ##
+    # @param  [Hash{String => String}] env
+    # @return [Array(Integer, Hash, #each)]
+    # @see    http://rack.rubyforge.org/doc/SPEC.html
+    def call(env)
+      request = Rack::Request.new(env)
+      allowed?(request) ? app.call(env) : rate_limit_exceeded
+    end
+
+    ##
+    # Returns `false` if the rate limit has been exceeded for the given
+    # `request`, or `true` otherwise.
+    #
+    # Override this method in subclasses that implement custom rate limiter
+    # strategies.
+    #
+    # @param  [Rack::Request] request
+    # @return [Boolean]
+    def allowed?(request)
+      case
+        when whitelisted?(request) then true
+        when blacklisted?(request) then false
+        else true # override in subclasses
+      end
+    end
+
+    ##
+    # Returns `true` if the originator of the given `request` is whitelisted
+    # (not subject to further rate limits).
+    #
+    # The default implementation always returns `false`. Override this
+    # method in a subclass to implement custom whitelisting logic.
+    #
+    # @param  [Rack::Request] request
+    # @return [Boolean]
+    # @abstract
+    def whitelisted?(request)
+      false
+    end
+
+    ##
+    # Returns `true` if the originator of the given `request` is blacklisted
+    # (not honoring rate limits, and thus permanently forbidden access
+    # without the need to maintain further rate limit counters).
+    #
+    # The default implementation always returns `false`. Override this
+    # method in a subclass to implement custom blacklisting logic.
+    #
+    # @param  [Rack::Request] request
+    # @return [Boolean]
+    # @abstract
+    def blacklisted?(request)
+      false
+    end
+
+    protected
+
+    ##
+    # @return [Hash]
+    def cache
+      case cache = (@options[:cache] ||= {})
+        when Proc then cache.call
+        else cache
+      end
+    end
+
+    ##
+    # @param  [String] key
+    def cache_has?(key)
+      case
+        when cache.respond_to?(:has_key?)
+          cache.has_key?(key)
+        when cache.respond_to?(:get)
+          cache.get(key) rescue false
+        else false
+      end
+    end
+
+    ##
+    # @param  [String] key
+    # @return [Object]
+    def cache_get(key, default = nil)
+      case
+        when cache.respond_to?(:[])
+          cache[key] || default
+        when cache.respond_to?(:get)
+          cache.get(key) || default
+      end
+    end
+
+    ##
+    # @param  [String] key
+    # @param  [Object] value
+    # @return [void]
+    def cache_set(key, value)
+      case
+        when cache.respond_to?(:[]=)
+          cache[key] = value
+        when cache.respond_to?(:set)
+          cache.set(key, value)
+      end
+    end
+
+    ##
+    # @param  [Rack::Request] request
+    # @return [String]
+    def cache_key(request)
+      id = client_identifier(request)
+      case
+        when options.has_key?(:key)
+          options[:key].call(request)
+        when options.has_key?(:key_prefix)
+          [options[:key_prefix], id].join(':')
+        else id
+      end
+    end
+
+    ##
+    # @param  [Rack::Request] request
+    # @return [String]
+    def client_identifier(request)
+      request.ip.to_s
+    end
+
+    ##
+    # @param  [Rack::Request] request
+    # @return [Float]
+    def request_start_time(request)
+      case
+        when request.env.has_key?('HTTP_X_REQUEST_START')
+          request.env['HTTP_X_REQUEST_START'].to_f / 1000
+        else
+          Time.now.to_f
+      end
+    end
+
+    ##
+    # 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')
+    end
+
+    ##
+    # Outputs an HTTP `4xx` or `5xx` response.
+    #
+    # @param  [Integer]       code
+    # @param  [String, #to_s] message
+    # @return [Array(Integer, Hash, #each)]
+    def http_error(code, message = nil)
+      [code, {'Content-Type' => 'text/plain; charset=utf-8'},
+        http_status(code) + (message.nil? ? "\n" : " (#{message})\n")]
+    end
+
+    ##
+    # Returns the standard HTTP status message for the given status `code`.
+    #
+    # @param  [Integer] code
+    # @return [String]
+    def http_status(code)
+      [code, Rack::Utils::HTTP_STATUS_CODES[code]].join(' ')
+    end
+  end
+end; end

data/lib/rack/throttle/version.rb

@@ -1,7 +1,7 @@
-module Rack module Throttle
+module Rack; module Throttle
   module VERSION
     MAJOR = 0
-    MINOR = 0
+    MINOR = 1
     TINY  = 0
     EXTRA = nil
 
@@ -20,4 +20,4 @@ module Rack module Throttle
     # @return [Array(Integer, Integer, Integer)]
     def self.to_a() [MAJOR, MINOR, TINY] end
   end
-end end
+end; end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 0
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Arto Bendiken
@@ -14,13 +14,27 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-20 00:00:00 +01:00
+date: 2010-03-21 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: rack-test
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 3
+        version: 0.5.3
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -30,11 +44,11 @@ dependencies:
         - 0
         version: 1.3.0
   type: :development
-  version_requirements: *id001
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: yard
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -44,11 +58,11 @@ dependencies:
         - 3
         version: 0.5.3
   type: :development
-  version_requirements: *id002
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: rack
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -58,7 +72,7 @@ dependencies:
         - 0
         version: 1.0.0
   type: :runtime
-  version_requirements: *id003
+  version_requirements: *id004
 description: Rack middleware for rate-limiting HTTP requests.
 email: arto.bendiken@gmail.com
 executables: []
@@ -72,10 +86,14 @@ files:
 - README
 - UNLICENSE
 - VERSION
+- lib/rack/throttle/daily.rb
+- lib/rack/throttle/hourly.rb
+- lib/rack/throttle/interval.rb
+- lib/rack/throttle/limiter.rb
 - lib/rack/throttle/version.rb
 - lib/rack/throttle.rb
 has_rdoc: false
-homepage: http://github.com/datagraph/rack-throttle
+homepage: http://github.com/datagraph
 licenses: 
 - Public Domain
 post_install_message: