jduff-api-throttling 0.1.0

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,175 @@
+# 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>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,38 @@
+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"]
+  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: 1
+:patch: 0

data/lib/api_throttling.rb

@@ -0,0 +1,49 @@
+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}.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={})
+    auth = Rack::Auth::Basic::Request.new(env)
+    if auth.provided?
+      return bad_request unless auth.basic?
+		  begin
+		    cache = @handler.new(@options[:cache])
+		    key = "#{auth.username}_#{Time.now.strftime("%Y-%m-%d-%H")}"
+		    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
+    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"
+    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/handlers.rb

@@ -0,0 +1,46 @@
+module Handlers
+  # 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)
+  # 
+  # Once you have a new handler make sure it is required in here and added to the Handlers list,
+  # you can then initialize the middleware and pass :cache=>CACHE_NAME as an option.
+  class Handler
+    def initialize(object=nil)
+      @cache = object.is_a?(self.class.cache_class) ? object : self.class.cache_class.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 handles?(info)
+        info.to_s.downcase == cache_class.to_s.downcase || info.is_a?(self.cache_class)
+      end
+    
+      def cache_class(name = nil)
+        @cache_class = name if name
+        Object.const_get(@cache_class) if @cache_class
+      end
+    end
+  end
+  
+  %w(redis_handler memcache_handler).each do |handler|
+    require File.expand_path(File.dirname(__FILE__) + "/#{handler}")
+  end
+  
+  HANDLERS = [RedisHandler, MemCacheHandler]
+  
+  def self.cache_handler_for(info)
+    HANDLERS.detect{|handler| handler.handles?(info)}
+  end
+  
+end

data/lib/handlers/memcache_handler.rb

@@ -0,0 +1,15 @@
+require 'memcache'
+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
+
+  end
+end

data/lib/handlers/redis_handler.rb

@@ -0,0 +1,14 @@
+require 'redis'
+module Handlers
+  class RedisHandler < Handler
+    cache_class "Redis"
+    
+    def increment(key)
+      @cache.incr(key)
+    end
+    
+    def get(key)
+      @cache[key]
+    end
+  end
+end

data/test/test_api_throttling.rb

@@ -0,0 +1,39 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+require 'redis'
+
+#  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
+  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 setup
+    # 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("joe*").each do |key|
+		    r.delete key
+		  end
+		  r.keys("luc*").each do |key|
+		    r.delete key
+		  end
+    rescue Errno::ECONNREFUSED
+      assert false, "You need to start redis-server"
+    end
+  end
+  
+  def test_cache_handler_should_be_redis
+    assert_equal "Handlers::RedisHandler", app.to_app.instance_variable_get(:@handler).to_s
+  end
+  
+end

data/test/test_api_throttling_memcache.rb

@@ -0,0 +1,24 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+require 'memcache'
+
+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, :read_method=>"get", :write_method=>"add"
+      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,39 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+require 'redis'
+require 'memcache'
+
+class HandlersTest < Test::Unit::TestCase
+  
+  def setup
+    
+  end
+  
+  def test_redis_should_handle_redis
+    assert Handlers::RedisHandler.handles?(:redis)
+    assert Handlers::RedisHandler.handles?('redis')
+    assert Handlers::RedisHandler.handles?('Redis')
+    assert Handlers::RedisHandler.handles?(Redis.new)
+  end
+  
+  def test_redis_should_not_handle_memcache
+    assert !Handlers::RedisHandler.handles?(:memcache)
+    assert !Handlers::RedisHandler.handles?('memcache')
+    assert !Handlers::RedisHandler.handles?('MemCache')
+    assert !Handlers::RedisHandler.handles?(MemCache.new)
+  end
+  
+  def test_memcache_should_not_handle_redis
+    assert !Handlers::MemCacheHandler.handles?(:redis)
+    assert !Handlers::MemCacheHandler.handles?('redis')
+    assert !Handlers::MemCacheHandler.handles?('Redis')
+    assert !Handlers::MemCacheHandler.handles?(Redis.new)
+  end
+  
+  def test_memcache_should_handle_memcache
+    assert Handlers::MemCacheHandler.handles?(:memcache)
+    assert Handlers::MemCacheHandler.handles?('memcache')
+    assert Handlers::MemCacheHandler.handles?('MemCache')
+    assert Handlers::MemCacheHandler.handles?(MemCache.new)
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,61 @@
+require 'rubygems'
+require 'rack/test'
+require 'test/unit'
+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"
+    get '/'
+    assert_equal 200, last_response.status
+    get '/'
+    assert_equal 200, last_response.status
+    get '/'
+    assert_equal 200, last_response.status
+    get '/'
+    assert_equal 503, last_response.status
+    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" 
+    get '/'
+    get '/'
+    get '/'
+    get '/'
+    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"
+    get '/'
+    get '/'
+    get '/'
+    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"
+    get '/'
+    get '/'
+    get '/'
+    get '/'
+    assert_equal 503, last_response.status
+    assert last_response.headers['Retry-After'].to_i <= (60 * 60)
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: jduff-api-throttling
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Luc Castera
+- John Duff
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-03 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+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/handlers.rb
+- lib/handlers/memcache_handler.rb
+- lib/handlers/redis_handler.rb
+- test/test_api_throttling.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
+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.2.0
+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_memcache.rb
+- test/test_handlers.rb
+- test/test_helper.rb