christoph-buente-api-throttling 0.2.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Luc Castera
+ 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+ 
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+ 
+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 OR COPYRIGHT HOLDERS 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.

data/README.md

@@ -0,0 +1,197 @@
+# Rack Middleware for Api Throttling
+
+<p>I will show you a technique to impose a rate limit (aka API Throttling) on a Ruby Web Service. I will be using Rack middleware so you can use this no matter what Ruby Web Framework you are using, as long as it is Rack-compliant.</p>
+
+<h2>Installation</h2>
+<p>This middleware has recently been gemmified, you can install the latest gem using:</p>
+<pre>sudo gem install jduff-api-throttling</pre>
+<p>If you prefer to have the latest source it can be found at http://github.com/jduff/api-throttling/tree (this is a fork of http://github.com/dambalah/api-throttling/tree with a number of recent changes)</p>
+
+<h2>Usage</h2>
+<p>In your rack application simply use the middleware and pass it some options</p>
+<pre>use ApiThrottling, :requests_per_hour => 3</pre>
+<p>This will setup throttling with a limit of 3 requests per hour and will use a Redis cache to keep track of it. By default Rack::Auth::Basic is used to limit the requests on a per user basis.</p>
+<p>A number of options can be passed to the middleware so it can be configured as needed for your stack.</p>
+<pre>:cache=>:redis # :memcache, :hash are supported. you can also pass in an instance of those caches, or even Rails.cache</pre>
+<pre>:auth=>false # if your middleware is doing authentication somewhere else</pre>
+<pre>:key=>Proc.new{|env,auth| "#{env['PATH_INFO']}_#{Time.now.strftime("%Y-%m-%d-%H")}" } # to customize how the cache key is generated</pre>
+
+<p>An example using all the options might look something like this:</p>
+<pre>
+  CACHE = MemCache.new
+  use ApiThrottling, :requests_per_hour => 100, :cache=>CACHE, :auth=>false, 
+                     :key=>Proc.new{|env,auth| "#{env['PATH_INFO']}_#{Time.now.strftime("%Y-%m-%d-%H")}" } 
+</pre>
+<p>This will limit requests to 100 per hour per url ('/home' will be tracked separately from '/users') keeping track by storing the counts with MemCache.</p>
+
+<h2>Introduction to Rack</h2>
+
+<p>There are plenty of <a href="http://jasonseifer.com/2009/04/08/32-rack-resources-to-get-you-started">great resources</a> to learn the basic of Rack so I will not be explaining how Rack works here but you will need to understand it in order to follow this post. I highly recommend watching the <a href="http://remi.org/2009/02/19/rack-basics.html">three</a> <a href="http://remi.org/2009/02/24/rack-part-2.html">Rack</a> <a href="http://remi.org/2009/02/28/rack-part-3-middleware.html">screencasts</a> from <a href="http://remi.org/">Remi</a> to get started with Rack.</p>
+
+<h2>Basic Rack Application</h2>
+
+<p>First, make sure you have the <a href="http://code.macournoyer.com/thin/">thin webserver</a> installed.</p>
+
+<pre>sudo gem install thin</pre>
+
+<p>We are going to use the following 'Hello World' Rack application to test our API Throttling middleware.</p> 
+
+<pre>
+use Rack::ShowExceptions
+use Rack::Lint
+
+run lambda {|env| [200, { 'Content-Type' => 'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+</pre>
+
+
+<p>Save this code in a file called <em>config.ru</em> and then you can run it with the thin webserver, using the following command:</p>
+
+<pre>thin --rackup config.ru start</pre>
+
+<p>Now you can open another terminal window (or a browser) to test that this is working as expected:</p>
+
+<pre>curl -i http://localhost:3000</pre>
+
+<p>The -i option tells curl to include the HTTP-header in the output so you should see the following:</p>
+
+<pre>
+$ curl -i http://localhost:3000
+HTTP/1.1 200 OK
+Content-Type: text/plain
+Content-Length: 12
+Connection: keep-alive
+Server: thin 1.0.0 codename That's What She Said
+
+Hello World!
+</pre>
+
+<p>At this point, we have a basic rack application that we can use to test our rack middleware. Now let's get started.</p>
+
+
+<h2>Redis</h2>
+
+<p>We need a way to memorize the number of requests that users are making to our web service if we want to limit the rate at which they can use the API. Every time they make a request, we want to check if they've gone past their rate limit before we respond to the request. We also want to store the fact that they've just made a request. Since every call to our web service requires this check and memorization process, we would like this to be done as fast as possible.</p>
+
+<p>This is where Redis comes in. Redis is a super-fast key-value database that we've highlighted <a href="http://blog.messagepub.com/2009/04/20/project-spotlight-redis-a-fast-data-structure-database/">in a previous blog post</a>. It can do about 110,000 SETs per second, about 81,000 GETs per second. That's the kind of performance that we are looking for since we would not like our 'rate limiting' middleware to reduce the performance of our web service.</p>
+
+<p>Install the redis ruby client library with <pre>sudo gem install ezmobius-redis-rb</pre></p>
+
+
+<h2>Our Rack Middleware</h2>
+
+<p>We are assuming that the web service is using HTTP Basic Authentication. You could use another type of authentication and adapt the code to fit your model.</p>
+
+<p>Our rack middleware will do the following:</p>
+<ul>
+  <li>For every request received, increment a key in our database. The key string will consists of the authenticated username followed by a timestamp for the current hour. For example, for a user called joe, the key would be: <em><strong>joe_2009-05-01-12</em></strong></li>
+  <li>If the value of that key is less than our 'maximum requests per hour limit', then return an HTTP Response with a status code of 503, indicating that the user has gone over his rate limit.</li>
+  <li>If the value of the key is less than the maximum requests per hour limit, then allow the user's request to go through.</li>
+</ul>
+
+<p>Redis has an atomic <a href="http://code.google.com/p/redis/wiki/IncrCommand">INCR command</a> that is the perfect fit for our use case. It increments the key value by one. If the key does not exist, it sets the key to the value of "0" and then increments it. Awesome! We don't even need to write our own logic to check if the key exists before incrementing it, Redis takes care of that for us.</p>
+
+<pre>
+r = Redis.new
+key = "#{auth.username}_#{Time.now.strftime("%Y-%m-%d-%H")}"
+r.incr(key)
+return over_rate_limit if r[key].to_i > @options[:requests_per_hour]
+</pre>
+
+<p>If our redis-server is not running, rather than throwing an error affecting all our users, we will let all the requests pass through by catching the exception and doing nothing. That means that if your redis-server goes down, you are no longer throttling the use of your web service so you need to make sure it's always running (using <a href="http://mmonit.com/monit/">monit</a> or <a href="http://god.rubyforge.org/">god</a>, for example).</p>
+
+<p>Finally, we want anyone who might use this Rack middleware to be able to set their limit via the <em>requests_per_hour</em> option.</p>
+
+<p>The full code for our middleware is below. You can also find it at <a href="https://github.com/dambalah/api-throttling">github.com/dambalah/api-throttling</a>.</p>
+
+<pre>
+require 'rubygems'
+require 'rack'
+require 'redis'
+
+class ApiThrottling
+  def initialize(app, options={})
+    @app = app
+    @options = {:requests_per_hour => 60}.merge(options)
+  end
+  
+  def call(env, options={})
+    auth = Rack::Auth::Basic::Request.new(env)
+    if auth.provided?
+      return bad_request unless auth.basic?
+		  begin
+		    r = Redis.new
+		    key = "#{auth.username}_#{Time.now.strftime("%Y-%m-%d-%H")}"
+		    r.incr(key)
+		    return over_rate_limit if r[key].to_i > @options[:requests_per_hour]
+		  rescue Errno::ECONNREFUSED
+		    # If Redis-server is not running, instead of throwing an error, we simply do not throttle the API
+		    # It's better if your service is up and running but not throttling API, then to have it throw errors for all users
+		    # Make sure you monitor your redis-server so that it's never down. monit is a great tool for that.
+		  end
+    end
+    @app.call(env)
+  end
+  
+  def bad_request
+    body_text = "Bad Request"
+    [ 400, { 'Content-Type' => 'text/plain', 'Content-Length' => body_text.size.to_s }, [body_text] ]
+  end
+  
+  def over_rate_limit
+    body_text = "Over Rate Limit"
+    [ 503, { 'Content-Type' => 'text/plain', 'Content-Length' => body_text.size.to_s }, [body_text] ]
+  end
+end
+</pre>
+
+<p>To use it on our 'Hello World' rack application, simply add it with the <em>use</em> keyword and the <em>:requests_per_hour</em> option:</p>
+
+<pre>
+require 'api_throttling'
+
+use Rack::Lint
+use Rack::ShowExceptions
+use ApiThrottling, :requests_per_hour => 3
+
+run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+</pre>
+
+<p><strong>That's it!</strong> Make sure your <em>redis-server</em> is running on port 6379 and try making calls to your api with curl. The first 3 calls will be succesful but the next ones will block because you've reached the limit that we've set:</p>
+
+<pre>
+$ curl -i http://joe@localhost:3000
+HTTP/1.1 200 OK
+Content-Type: text/plain
+Content-Length: 12
+Connection: keep-alive
+Server: thin 1.0.0 codename That's What She Said
+
+Hello World!
+
+$ curl -i http://joe@localhost:3000
+HTTP/1.1 200 OK
+Content-Type: text/plain
+Content-Length: 12
+Connection: keep-alive
+Server: thin 1.0.0 codename That's What She Said
+
+Hello World!
+
+$ curl -i http://joe@localhost:3000
+HTTP/1.1 200 OK
+Content-Type: text/plain
+Content-Length: 12
+Connection: keep-alive
+Server: thin 1.0.0 codename That's What She Said
+
+Hello World!
+
+$ curl -i http://joe@localhost:3000
+HTTP/1.1 503 Service Unavailable
+Content-Type: text/plain
+Content-Length: 15
+Connection: keep-alive
+Server: thin 1.0.0 codename That's What She Said
+
+Over Rate Limit
+</pre>

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "api-throttling"
+    gemspec.summary = "Rack Middleware to impose a rate limit on a web service (aka API Throttling)"
+    gemspec.email = "duff.john@gmail.com"
+    gemspec.homepage = "http://github.com/jduff/api-throttling/tree"
+    gemspec.description = "TODO"
+    gemspec.authors = ["Luc Castera", "John Duff"]
+    gemspec.add_development_dependency('context')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test

data/TODO.md

@@ -0,0 +1,6 @@
+# TODO
+
+
+_Nothing_
+
+_Suggestions Welcomed_

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 2
+:patch: 1

data/lib/api_throttling.rb

@@ -0,0 +1,73 @@
+require 'rubygems'
+require 'rack'
+require File.expand_path(File.dirname(__FILE__) + '/handlers/handlers')
+
+class ApiThrottling
+  def initialize(app, options={})
+    @app = app
+    @options = {:requests_per_hour => 60, :cache=>:redis, :auth=>true}.merge(options)
+    @handler = Handlers.cache_handler_for(@options[:cache])
+    raise "Sorry, we couldn't find a handler for the cache you specified: #{@options[:cache]}" unless @handler
+  end
+  
+  def call(env, options={})
+    if @options[:only] or @options[:except]
+      req = Rack::Request.new(env)
+      # call the app normally cause the path restriction didn't match
+      return @app.call(env) unless path_matches?(req.path)
+    end
+
+    if @options[:auth]
+      auth = Rack::Auth::Basic::Request.new(env)
+      return auth_required unless auth.provided?
+      return bad_request unless auth.basic?
+    end
+    
+    begin
+	    cache = @handler.new(@options[:cache])
+	    key = generate_key(env, auth)
+	    cache.increment(key)
+	    return over_rate_limit if cache.get(key).to_i > @options[:requests_per_hour]
+	  rescue Errno::ECONNREFUSED
+	    # If Redis-server is not running, instead of throwing an error, we simply do not throttle the API
+	    # It's better if your service is up and running but not throttling API, then to have it throw errors for all users
+	    # Make sure you monitor your redis-server so that it's never down. monit is a great tool for that.
+	  end
+    @app.call(env)
+  end
+  
+  def path_matches?(path)
+    only = @options[:only] || ''
+    except = @options[:except] || ' '
+    (path =~ /^#{only}/) and !(path =~ /^#{except}/)
+  end
+
+  def generate_key(env, auth)
+    return @options[:key].call(env, auth) if @options[:key]
+    auth ? "#{auth.username}_#{Time.now.strftime("%Y-%m-%d-%H")}" : "#{Time.now.strftime("%Y-%m-%d-%H")}"
+  end
+  
+  def bad_request
+    body_text = "Bad Request"
+    [ 400, { 'Content-Type' => 'text/plain', 'Content-Length' => body_text.size.to_s }, [body_text] ]
+  end
+  
+  def auth_required
+    body_text = "Authorization Required"
+    [ 401, { 'Content-Type' => 'text/plain', 'Content-Length' => body_text.size.to_s }, [body_text] ]
+  end
+  
+  def over_rate_limit
+    body_text = "Over Rate Limit"
+    retry_after_in_seconds = (60 - Time.now.min) * 60
+    [ 503, 
+      { 'Content-Type' => 'text/plain', 
+        'Content-Length' => body_text.size.to_s, 
+        'Retry-After' => retry_after_in_seconds.to_s 
+      }, 
+      [body_text]
+    ]
+  end
+end
+
+

data/lib/handlers/active_support_cache_store_handler.rb

@@ -0,0 +1,21 @@
+module Handlers
+  class ActiveSupportCacheStoreHandler < Handler
+    
+    def initialize(object=nil)
+      raise "Must provide an existing ActiveSupport::Cache::Store" unless object.is_a?(ActiveSupport::Cache::Store)
+      @cache = object
+    end
+    
+    def increment(key)
+      @cache.write(key, (get(key)||0).to_i+1)
+    end
+    
+    def get(key)
+      @cache.read(key)
+    end
+    
+    %w(MemCacheStore FileStore MemoryStore SynchronizedMemoryStore DRbStore CompressedMemCacheStore).each do |store|
+      Handlers.add_handler(self, "ActiveSupport::Cache::#{store}".downcase)
+    end
+  end
+end

data/lib/handlers/handlers.rb

@@ -0,0 +1,46 @@
+module Handlers
+  HANDLERS = {}
+    
+  def self.cache_handler_for(info)
+    HANDLERS[info.to_s.downcase] || HANDLERS[info.class.to_s.downcase]
+  end
+  
+  def self.add_handler(handler, key=nil)
+    HANDLERS[key || handler.cache_class.downcase] = handler
+  end
+  
+  # creating a new cache handler is as simple as extending from the handler class,
+  # setting the class to use as the cache by calling cache_class("Redis")
+  # and then implementing the increment and get methods for that cache type.
+  #
+  # If you don't want to extend from Handler you can just create a class that implements
+  # increment(key), get(key) and handles?(info)
+  # 
+  # you can then initialize the middleware and pass :cache=>CACHE_NAME as an option.
+  class Handler
+    def initialize(object=nil)
+      cache = Object.const_get(self.class.cache_class)
+      @cache = object.is_a?(cache) ? object : cache.new
+    end
+    
+    def increment(key)
+      raise "Cache Handlers must implement an increment method"
+    end
+    
+    def get(key)
+      raise "Cache Handlers must implement a get method"
+    end
+    
+    class << self    
+  
+      def cache_class(name = nil)
+        @cache_class = name if name
+        @cache_class
+      end
+    end
+  end
+
+  %w(redis_handler memcache_handler hash_handler active_support_cache_store_handler).each do |handler|
+    require File.expand_path(File.dirname(__FILE__) + "/#{handler}")
+  end  
+end

data/lib/handlers/hash_handler.rb

@@ -0,0 +1,15 @@
+module Handlers
+  class HashHandler < Handler
+    cache_class "Hash"
+    
+    def increment(key)
+      @cache[key] = (get(key)||0).to_i+1
+    end
+    
+    def get(key)
+      @cache[key]
+    end
+    
+    Handlers.add_handler self
+  end
+end

data/lib/handlers/memcache_handler.rb

@@ -0,0 +1,15 @@
+module Handlers
+  class MemCacheHandler < Handler
+    cache_class "MemCache"
+    
+    def increment(key)
+      @cache.set(key, (get(key)||0).to_i+1)
+    end
+    
+    def get(key)
+      @cache.get(key)
+    end
+    
+    Handlers.add_handler self
+  end
+end

data/lib/handlers/redis_handler.rb

@@ -0,0 +1,15 @@
+module Handlers
+  class RedisHandler < Handler
+    cache_class "Redis"
+    
+    def increment(key)
+      @cache.incr(key)
+    end
+    
+    def get(key)
+      @cache[key]
+    end
+    
+    Handlers.add_handler self
+  end
+end

data/test/test_api_throttling.rb

@@ -0,0 +1,221 @@
+require 'redis'
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+#  To Run this test, you need to have the redis-server running.
+#  And you need to have rack-test gem installed: sudo gem install rack-test
+#  For more information on rack-test, visit: http://github.com/brynary/rack-test
+
+class ApiThrottlingTest < Test::Unit::TestCase
+  include Rack::Test::Methods
+  
+  context "using redis" do
+    before do
+      # Delete all the keys for 'joe' in Redis so that every test starts fresh
+      # Having this here also helps as a reminder to start redis-server
+      begin
+  		  r = Redis.new
+  		  r.keys("*").each do |key|
+  		    r.delete key
+  		  end
+  		  
+      rescue Errno::ECONNREFUSED
+        assert false, "You need to start redis-server"
+      end
+    end
+    
+    context "with authentication required" do
+      include BasicTests
+      
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+    
+      def test_cache_handler_should_be_redis
+        assert_equal "Handlers::RedisHandler", app.to_app.instance_variable_get(:@handler).to_s
+      end
+      
+    end
+    
+    context "without authentication required" do
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, :auth=>false
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+
+      def test_should_not_require_authorization
+        3.times do
+          get '/'
+          assert_equal 200, last_response.status
+        end
+        get '/'
+        assert_equal 503, last_response.status
+      end
+    end
+    
+    context "with rate limit key based on url" do
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, 
+                             :key=>Proc.new{ |env,auth| "#{auth.username}_#{env['PATH_INFO']}_#{Time.now.strftime("%Y-%m-%d-%H")}" }
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+      
+      test "should throttle requests based on the user and url called" do
+        authorize "joe", "secret"
+        3.times do
+          get '/'
+          assert_equal 200, last_response.status
+        end
+        get '/'
+        assert_equal 503, last_response.status
+        
+        3.times do
+          get '/awesome'
+          assert_equal 200, last_response.status
+        end
+        get '/awesome'
+        assert_equal 503, last_response.status
+        
+        authorize "luc", "secret"
+        get '/awesome'
+        assert_equal 200, last_response.status
+        
+        get '/'
+        assert_equal 200, last_response.status
+      end
+    end
+
+    context "with path restriction :only" do
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, :only => '/awesome'
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+
+      test "should not throttle request to /" do
+        5.times do
+          get '/'
+          assert_equal 200, last_response.status
+        end
+      end
+
+      test "should throttle request to /awesome" do
+        3.times do
+          get '/awesome'
+          assert_equal 200, last_response.status
+        end
+        get '/awesome'
+        assert_equal 503, last_response.status
+      end
+    end
+
+    context "with path restrictions :except" do
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, :except => '/awesome'
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+
+      test "should not throttle request to /awesome" do
+        5.times do
+          get '/awesome'
+          assert_equal 200, last_response.status
+        end
+      end
+
+      test "should throttle request to /" do
+        3.times do
+          get '/'
+          assert_equal 200, last_response.status
+        end
+        get '/'
+        assert_equal 503, last_response.status
+      end
+    end
+
+    conteyt "with path rescrictions :only and :except" do
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, :only => '/awesome', :except => '/awesome/foo'
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+
+      test "should not throttle request to /" do
+        5.times do
+          get '/'
+          assert_equal 200, last_response.status
+        end
+      end
+
+      test "should throttle request to /awesome" do
+        3.times do
+          get '/awesome'
+          assert_equal 200, last_response.status
+        end
+        get '/awesome'
+        assert_equal 503, last_response.status
+      end
+
+      test "should not throttle request to /awesome/foo" do
+        5.times do
+          get '/awesome/foo'
+          assert_equal 200, last_response.status
+        end
+      end
+    end
+  end
+  
+  context "using active support cache store" do
+    require 'active_support'
+    
+    context "memory store" do
+      include BasicTests
+
+      before do
+        @@cache_store = ActiveSupport::Cache.lookup_store(:memory_store)
+      end
+      
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, :cache=>@@cache_store
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+      
+      def test_cache_handler_should_be_memcache
+        assert_equal "Handlers::ActiveSupportCacheStoreHandler", app.to_app.instance_variable_get(:@handler).to_s
+      end
+    end
+    
+    context "memcache store" do
+      include BasicTests
+      
+      
+      before do
+        @@cache_store = ActiveSupport::Cache.lookup_store(:memCache_store)
+        @@cache_store.clear
+      end
+      
+      def app
+        app = Rack::Builder.new {
+          use ApiThrottling, :requests_per_hour => 3, :cache=>@@cache_store
+          run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+        }
+      end
+      
+      def test_cache_handler_should_be_memcache
+        assert_equal "Handlers::ActiveSupportCacheStoreHandler", app.to_app.instance_variable_get(:@handler).to_s
+      end
+    end
+  end
+  
+end

data/test/test_api_throttling_hash.rb

@@ -0,0 +1,23 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class TestApiThrottlingHash < Test::Unit::TestCase
+  include Rack::Test::Methods
+  include BasicTests
+  HASH = Hash.new
+
+  def app
+    app = Rack::Builder.new {
+      use ApiThrottling, :requests_per_hour => 3, :cache => HASH
+      run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+    }
+  end
+  
+  def setup
+    HASH.replace({})
+  end
+  
+  def test_cache_handler_should_be_memcache
+    assert_equal "Handlers::HashHandler", app.to_app.instance_variable_get(:@handler).to_s
+  end
+
+end

data/test/test_api_throttling_memcache.rb

@@ -0,0 +1,24 @@
+require 'memcache'
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class TestApiThrottlingMemcache < Test::Unit::TestCase
+  include Rack::Test::Methods
+  include BasicTests
+  CACHE = MemCache.new 'localhost:11211', :namespace=>'api-throttling-tests'
+
+  def app
+    app = Rack::Builder.new {
+      use ApiThrottling, :requests_per_hour => 3, :cache => CACHE
+      run lambda {|env| [200, {'Content-Type' =>  'text/plain', 'Content-Length' => '12'}, ["Hello World!"] ] }
+    }
+  end
+  
+  def setup
+    CACHE.flush_all
+  end
+  
+  def test_cache_handler_should_be_memcache
+    assert_equal "Handlers::MemCacheHandler", app.to_app.instance_variable_get(:@handler).to_s
+  end
+
+end

data/test/test_handlers.rb

@@ -0,0 +1,25 @@
+require 'redis'
+require 'memcache'
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class HandlersTest < Test::Unit::TestCase
+
+  should "select redis handler" do
+    [:redis, 'redis', 'Redis', Redis.new].each do |key|
+      assert_equal Handlers::RedisHandler, Handlers.cache_handler_for(key)
+    end
+  end
+
+  should "select memcache handler" do
+    [:memcache, 'memcache', 'MemCache', MemCache.new].each do |key|
+      assert_equal Handlers::MemCacheHandler, Handlers.cache_handler_for(key)
+    end
+  end
+  
+  should "select hash handler" do
+    [:hash, 'hash', 'Hash', {}].each do |key|
+      assert_equal Handlers::HashHandler, Handlers.cache_handler_for(key)
+    end
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rack/test'
+require 'test/unit'
+require 'context'
+require File.expand_path(File.dirname(__FILE__) + '/../lib/api_throttling')
+
+# this way we can include the module for any of the handler tests
+module BasicTests
+  def test_first_request_should_return_hello_world
+    authorize "joe", "secret"
+    get '/'
+    assert_equal 200, last_response.status
+    assert_equal "Hello World!", last_response.body    
+  end
+  
+  def test_fourth_request_should_be_blocked
+    authorize "joe", "secret"
+    3.times do
+      get '/'
+      assert_equal 200, last_response.status
+    end
+    get '/'
+    assert_equal 503, last_response.status
+  end
+  
+  def test_over_rate_limit_should_only_apply_to_user_that_went_over_the_limit
+    authorize "joe", "secret" 
+    5.times { get '/' }
+    assert_equal 503, last_response.status
+    authorize "luc", "secret"
+    get '/'
+    assert_equal 200, last_response.status
+  end
+  
+  def test_over_rate_limit_should_return_a_retry_after_header
+    authorize "joe", "secret"
+    4.times { get '/' }
+    assert_equal 503, last_response.status
+    assert_not_nil last_response.headers['Retry-After']
+  end
+  
+  def test_retry_after_should_be_less_than_60_minutes
+    authorize "joe", "secret"
+    4.times { get '/' }
+    assert_equal 503, last_response.status
+    assert last_response.headers['Retry-After'].to_i <= (60 * 60)
+  end
+  
+  def test_should_require_authorization
+    get '/'
+    assert_equal 401, last_response.status
+  end
+
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: christoph-buente-api-throttling
+version: !ruby/object:Gem::Version 
+  version: 0.2.1
+platform: ruby
+authors: 
+- Luc Castera
+- John Duff
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-06 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: context
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: TODO
+email: duff.john@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- LICENSE
+- README.md
+- Rakefile
+- TODO.md
+- VERSION.yml
+- lib/api_throttling.rb
+- lib/handlers/active_support_cache_store_handler.rb
+- lib/handlers/handlers.rb
+- lib/handlers/hash_handler.rb
+- lib/handlers/memcache_handler.rb
+- lib/handlers/redis_handler.rb
+- test/test_api_throttling.rb
+- test/test_api_throttling_hash.rb
+- test/test_api_throttling_memcache.rb
+- test/test_handlers.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jduff/api-throttling/tree
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Rack Middleware to impose a rate limit on a web service (aka API Throttling)
+test_files: 
+- test/test_api_throttling.rb
+- test/test_api_throttling_hash.rb
+- test/test_api_throttling_memcache.rb
+- test/test_handlers.rb
+- test/test_helper.rb