redis_knock 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw*
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+vendor/bundle/*

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format progress

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,80 @@
+Ruby HTTP Throttle Control Engine using Redis 
+=============================================
+
+This gem implements a simple HTTP throttle control using [Redis][] as database engine to store rate-limiting IP's.
+
+Why not rack-throttle?
+------------------------
+
+The gem [rack-throttle][] works with the same principle and does very well the job, but stores IP's and never clears the database.
+The main goal of Redis Knock is the use of Redis **[expire][]** command, that removes the key after X seconds.
+
+Usage
+-----
+
+### Using in your Rails Controller with before_filter
+
+    # app/controllers/simple_controller.rb
+
+    require 'redis_knock'
+
+    class SimpleController < ApplicationController
+      before_filter :check_throttle
+
+      private
+      def check_throttle
+        control = RedisKnock::Control.new limit: 1000, interval: 1.hour, redis: { host: 'localhost', port: 6379, db: 1 }
+
+        render(text: 'Rate limit exceeded', status: :forbidden) and return unless control.allowed?(request)
+      end
+    end
+
+### Using as a Rack Middleware in your Rails app
+
+    # config/application.rb
+
+    class Application < Rails::Application
+      config.middleware.use RedisKnock::Middleware, limit: 1000, interval: 1.hour, redis: { host: 'localhost', port: 6379, db: 1 }
+    end
+
+### Using in your Sinatra app
+
+    # a_sinatra_application.rb
+
+    require 'sinatra'
+    require 'redis_knock'
+
+    use RedisKnock::Middleware, limit: 1000, interval: 3600, redis: { host: 'localhost', port: 6379, db: 1 }
+
+    get '/' do
+      'Hello World!'
+    end
+
+Dependencies
+------------
+
+* redis gem
+* Redis server version >= 2.1
+
+Installation
+------------
+
+### With rubygems:
+
+    $ [sudo] gem install redis_knock
+
+Authors
+-------
+
+* Marcelo Correia Pinheiro - <http://salizzar.net/>
+
+License
+-------
+
+RedisKnock is free and unencumbered pubic domain software. For more
+information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
+
+[rack-throttle]:  https://raw.github.com/datagraph/rack-throttle
+[Redis]:          http://redis.io/
+[expire]:         http://redis.io/commands/expire
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/UNLICENSE

@@ -0,0 +1,25 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>
+

data/lib/redis-knock.rb

@@ -0,0 +1,4 @@
+# encoding: UTF-8
+
+require 'redis_knock'
+

data/lib/redis_knock/connection_error.rb

@@ -0,0 +1,7 @@
+# encoding: UTF-8
+
+module RedisKnock
+  class ConnectionError < Exception
+  end
+end
+

data/lib/redis_knock/control.rb

@@ -0,0 +1,48 @@
+# encoding: UTF-8
+
+module RedisKnock
+  class Control
+    def initialize(options)
+      check! options
+
+      @client = get_connection options[:redis]
+      @limit = options[:limit]
+      @interval = options[:interval]
+    end
+
+    def allowed?(request)
+      cache_key = get_cache_key request
+
+      count = @client.incr cache_key
+      @client.expire(cache_key, @interval) if count == 1
+
+      count <= @limit
+    end
+
+    private
+
+    def check!(options)
+      raise ArgumentError.new('A limit must be supplied') if options[:limit].nil?
+      raise ArgumentError.new('A interval must be supplied') if options[:interval].nil?
+
+      redis_opts = options[:redis]
+      raise ArgumentError.new('Redis connection params must be supplied') if redis_opts.nil? || redis_opts.empty?
+      raise ArgumentError.new('Redis host must be supplied') if redis_opts[:host].nil?
+      raise ArgumentError.new('Redis port must be supplied') if redis_opts[:port].nil?
+      raise ArgumentError.new('Redis database must be supplied') if redis_opts[:db].nil?
+    end
+
+    def get_connection(options)
+      begin
+        Redis.new options
+      rescue Exception => e
+        raise ConnectionError.new("Cannot connect to Redis server: #{e.message}")
+      end
+    end
+
+    def get_cache_key(request)
+      request.ip.to_s
+    end
+  end
+end
+

data/lib/redis_knock/middleware.rb

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+
+module RedisKnock
+  class Middleware
+    attr_reader :app, :options
+
+    def initialize(app, options = {})
+      @app, @options = app, options
+    end
+
+    def call(env)
+      request = Rack::Request.new env
+      control = RedisKnock::Control.new options
+      control.allowed?(request) ? app.call(env) : limit_exceeded
+    end
+
+    private
+
+    def limit_exceeded
+      message = 'Rate limit exceeded'
+
+      headers = {}
+      headers['Content-Type'] = 'text/plain; charset=utf-8'
+      headers['Content-Length'] = message.length.to_s
+
+      [ 403, headers, [ message ] ]
+    end
+  end
+end
+

data/lib/redis_knock/version.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+
+module RedisKnock
+  VERSION = '0.0.1'
+end

data/lib/redis_knock.rb

@@ -0,0 +1,12 @@
+# encoding: UTF-8
+
+require 'redis'
+
+module RedisKnock
+  autoload :ConnectionFactory,  'redis_knock/connection_factory'
+  autoload :Control,            'redis_knock/control'
+  autoload :Middleware,         'redis_knock/middleware'
+  autoload :ConnectionError,    'redis_knock/connection_error'
+  autoload :Version,            'redis_knock/version'
+end
+

data/redis_knock.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "redis_knock/version"
+
+Gem::Specification.new do |s|
+  s.name        = "redis_knock"
+  s.version     = RedisKnock::VERSION
+  s.authors     = ["Marcelo Correia Pinheiro"]
+  s.email       = ["salizzar@gmail.com"]
+  s.homepage    = "https://github.com/salizzar/redis_knock"
+  s.summary     = %q{A Ruby HTTP Throttle Control}
+  s.description = %q{The gem redis_knock implements a HTTP Throttle Control engine using Redis to store rate-limiting IP's.}
+
+  s.rubyforge_project = "redis_knock"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency  'rake'
+  s.add_development_dependency  'rspec'
+  s.add_development_dependency  'rack-test'
+  s.add_runtime_dependency      'redis'
+end

data/spec/lib/redis_knock/control_spec.rb

@@ -0,0 +1,103 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+describe RedisKnock::Control do
+  let(:subject)       { RedisKnock::Control }
+  let(:host)          { 'localhost' }
+  let(:port)          { 6379 }
+  let(:db)            { 1 }
+  let(:interval)      { 3600 }
+  let(:limit)         { 1000 }
+  let(:ip)            { '127.0.0.1' }
+  let(:request)       { mock(:ip => ip) }
+  let(:redis_client)  { mock 'An Redis connection' }
+  let(:redis_options) { { :host => host, :port => port, :db => db } }
+  let(:options)       { { :limit => limit, :interval => interval, :redis => redis_options } }
+
+  context 'invalid arguments validation' do
+    it 'raises ArgumentError if limit is not informed' do
+      options.delete :limit
+
+      error = ArgumentError.new 'A limit must be supplied'
+      expect { subject.new options }.to raise_error(error.class, error.message)
+    end
+
+    it 'raises ArgumentErroro if interval is not informed' do
+      options.delete :interval
+
+      error = ArgumentError.new 'A interval must be supplied'
+      expect { subject.new options }.to raise_error(error.class, error.message)
+    end
+
+    context 'Redis connection params' do
+      it 'raises ArgumentError if redis connection params are not informed' do
+        options.delete :redis
+
+        error = ArgumentError.new 'Redis connection params must be supplied'
+        expect { subject.new options }.to raise_error(error.class, error.message)
+      end
+
+      it 'raises ArgumentError if host is not informed' do
+        redis_options.delete :host
+
+        error = ArgumentError.new 'Redis host must be supplied'
+        expect { subject.new options }.to raise_error(error.class, error.message)
+      end
+
+      it 'raises ArgumentError if port is not informed' do
+        redis_options.delete :port
+
+        error = ArgumentError.new 'Redis port must be supplied'
+        expect { subject.new options }.to raise_error(error.class, error.message)
+      end
+
+      it 'raises ArgumentError if database is not informed' do
+        redis_options.delete :db
+
+        error = ArgumentError.new 'Redis database must be supplied'
+        expect { subject.new options }.to raise_error(error.class, error.message)
+      end
+    end
+  end
+
+  context 'when cannot connect to Redis server' do
+    it 'raises ConnectionError' do
+      Redis.should_receive(:new).and_raise('An error')
+
+      error = RedisKnock::ConnectionError.new 'Cannot connect to Redis server: An error'
+      expect { subject.new options }.to raise_error(error.class, error.message)
+    end
+  end
+
+  context 'checking for allowed requests' do
+    before :each do
+      Redis.should_receive(:new).with(redis_options).and_return(redis_client)
+    end
+
+    it 'expires key if is first request' do
+      redis_client.should_receive(:incr).and_return(1)
+      redis_client.should_receive(:expire).with(ip, interval)
+
+      control = subject.new options
+      control.should be_allowed(request)
+    end
+
+    it 'returns true when limit is not reached' do
+      redis_client.should_not_receive(:expire)
+      redis_client.should_receive(:incr).and_return(limit - 1)
+
+      control = subject.new options
+      control.should be_allowed(request)
+    end
+
+    it 'returns false when limit is reached' do
+      redis_client.should_not_receive(:expire)
+      redis_client.should_receive(:incr).and_return(limit + 1)
+
+      control = subject.new options
+      control.should_not be_allowed(request)
+    end
+  end
+end
+

data/spec/lib/redis_knock/middleware_spec.rb

@@ -0,0 +1,47 @@
+# encoding: UTF-8
+
+require 'spec_helper'
+
+describe RedisKnock::Middleware do
+  let(:redis_options) { { :host => 'localhost', :port => 6379, :db => 1 } }
+  let(:options)       { { :limit => 1000, :interval => 3600, :redis => redis_options } }
+  let(:target_app)    { get_app }
+  let(:app)           { RedisKnock::Middleware.new target_app, options }
+  let(:control)       { mock 'A Redis Throttle Control' }
+
+  context 'performing throttle check' do
+    before :each do
+      RedisKnock::Control.should_receive(:new).and_return(control)
+    end
+
+    context 'with a allowed request' do
+      it 'process if limit is not reached' do
+        target_app.should_receive(:call).and_return([ 200, {}, [ 'An response body' ] ])
+        control.should_receive(:allowed?).and_return(true)
+
+        get '/'
+        last_response.status.should == 200
+        last_response.body.should == 'An response body'
+      end
+    end
+
+    context 'with a not allowed request' do
+      before :each do
+        control.should_receive(:allowed?).and_return(false)
+      end
+
+      it 'returns HTTP 403 Forbidden if limit was reached' do
+        get '/'
+        last_response.status.should == 403
+        last_response.body.should == 'Rate limit exceeded'
+      end
+
+      it 'returns content-type and retry-after HTTP headers when is not allowed' do
+        get '/'
+        last_response.headers['Content-Type'].should == 'text/plain; charset=utf-8'
+        last_response.headers['Content-Length'].should == 'Rate limit exceeded'.length.to_s
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+# encoding: UTF-8
+
+require 'bundler'
+require 'rspec'
+require 'rack/test'
+require 'redis_knock'
+
+RSpec.configure do |config|
+  config.include Rack::Test::Methods
+
+  def get_app
+    @app ||= mock 'An app'
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: redis_knock
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Marcelo Correia Pinheiro
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70260527478660 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70260527478660
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70260527403560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70260527403560
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: &70260527402640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70260527402640
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &70260527401620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70260527401620
+description: The gem redis_knock implements a HTTP Throttle Control engine using Redis
+  to store rate-limiting IP's.
+email:
+- salizzar@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- README.md
+- Rakefile
+- UNLICENSE
+- lib/redis-knock.rb
+- lib/redis_knock.rb
+- lib/redis_knock/connection_error.rb
+- lib/redis_knock/control.rb
+- lib/redis_knock/middleware.rb
+- lib/redis_knock/version.rb
+- redis_knock.gemspec
+- spec/lib/redis_knock/control_spec.rb
+- spec/lib/redis_knock/middleware_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/salizzar/redis_knock
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: redis_knock
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A Ruby HTTP Throttle Control
+test_files:
+- spec/lib/redis_knock/control_spec.rb
+- spec/lib/redis_knock/middleware_spec.rb
+- spec/spec_helper.rb