rack-defense 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e47fe356fd72d70737af5ff0d64db8f823e1e93
-  data.tar.gz: 62972c5a9e0258ffccd3af644d9e191526686e2a
+  metadata.gz: 0c50757c35cc2da91b683042c9e3b756ec83512c
+  data.tar.gz: a491f2c431c5ccb04f5fd75b20314f6fc0e7a543
 SHA512:
-  metadata.gz: e09969ed7c4615439aa3f4dd105b992925cf48e7da9b0549f44c3f7757cbf8e4c46cdc5380edf0a66a5d3bb7c1bb8c2505062393a6600003dce6531f8b4f2840
-  data.tar.gz: c7258b578750efd00ce4046c8f3f6fa6daf97a0390a80b1a10df887bc22edf91894f7c6f49b00bfeda59724288c22dfc4e8fe776041ac457425c57a96d3b36e0
+  metadata.gz: bc05d56c2f0cfa059aee32d9d2a0158ae8f53f74eed2f8abdf69f051dc6cd3d3268ed4f7d260fc55bbd0744dc22c6cb0fd1d5b6228a66363f3ad5c97a7ab3d78
+  data.tar.gz: d99193f5823229cc5f155bf7b1f5cb1e7eab49af9aa7bf7aa733890a6fdafc35735a92ccab916dcafa2f4be6642235d8c9deac8212b43b148198c30eb545645e

data/README.md

@@ -8,11 +8,11 @@ A Rack middleware for throttling and filtering requests.
 [![Dependency Status](https://gemnasium.com/Sinbadsoft/rack-defense.svg)](https://gemnasium.com/Sinbadsoft/rack-defense)
 [![Gem Version](https://badge.fury.io/rb/rack-defense.svg)](http://badge.fury.io/rb/rack-defense)
 
-Rack::Defense is a Rack middleware that allows you to easily add request rate limiting and request filtering to your Rack based application (Ruby On Rails, Sinatra etc.).
+Rack::Defense is a Rack middleware that allows to easily add request rate limiting and request filtering to your Rack based application (Ruby On Rails, Sinatra etc.).
 
-* Throttling (aka rate limiting) happens on __sliding window__ using the provided period, request criteria and maximum request number. It uses Redis to track the request rate.
+* Request throttling (aka rate limiting) happens on __sliding window__ using the provided period, request criteria and maximum request number. It uses Redis to track the request rate.
 
-* Request filtering allows to reject requests based on provided critera.
+* Request filtering bans (rejects) requests based on provided criteria.
 
 Rack::Defense has a small footprint and only two dependencies: [rack](https://github.com/rack/rack) and [redis](https://github.com/redis/redis-rb).
 
@@ -26,19 +26,23 @@ Install the rack-defense gem; or add it to you Gemfile with bundler:
 # In your Gemfile
 gem 'rack-defense'
 ```
+
 Tell your app to use the Rack::Defense middleware. For Rails 3+ apps:
-```
+
+```ruby
 # In config/application.rb
 config.middleware.use Rack::Defense
 ```
 
 Or for Rackup files:
-```
+
+```ruby
 # In config.ru
 use Rack::Defense
 ```
 
-Add a `rack-defense.rb` file to `config/initalizers/`:
+Add a `rack-defense.rb` file to `config/initializers/`:
+
 ```ruby
 # In config/initializers/rack-defense.rb
 Rack::Defense.setup do |config|
@@ -47,11 +51,16 @@ end
 ```
 
 ## Throttling
-The Rack::Defense middleware evaluates the throttling criterias (lambdas) against the incoming request. If the return value is falsy, the request is not throttled. Otherwise, the returned value is used as a key to throttle the request. The returned key could be the request IP, user name, API token or any discriminator to throttle the requests against.
+
+The Rack::Defense middleware evaluates the throttling criteria (lambdas) against the incoming request.
+If the return value is falsy, the request is not throttled. Otherwise, the returned value is used as a key to
+throttle the request. The returned key could be the request IP, user name, API token or any discriminator to throttle
+the requests against.
 
 ### Examples
 
-Throttle POST requests for path `/login` with a maximum rate of 3 request per minute per IP
+Throttle POST requests for path `/login` with a maximum rate of 3 request per minute per IP:
+
 ```ruby
 Rack::Defense.setup do |config|
   config.throttle('login', 3, 60 * 1000) do |req|
@@ -60,7 +69,8 @@ Rack::Defense.setup do |config|
 end
 ```
 
-Throttle GET requests for path `/image` with a maximum rate of 50 request per second per API token
+Throttle GET requests for path `/api/*` with a maximum rate of 50 request per second per API token:
+
 ```ruby
 Rack::Defense.setup do |config|
   config.throttle('api', 50, 1000) do |req|
@@ -69,16 +79,30 @@ Rack::Defense.setup do |config|
 end
 ```
 
+Throttle POST requests for path `/aggregate/report` with a maximum rate of 10 requests per hour for a given logged in user. We assume here that we are using the [Warden](https://github.com/hassox/warden) middleware for authentication or any Warden based authentication wrapper, like [Devise](https://github.com/plataformatec/devise) in Rails.
+
+```ruby
+Rack::Defense.setup do |config|
+  config.throttle('aggregate_report', 10, 1.hour.in_milliseconds) do |req|
+    req.env['warden'].user.id if req.path == '/aggregate/report' && req.env['warden'].user
+  end 
+end
+```
+
 ### Redis Configuration
 
-Rack::Defense uses Redis to track request rates. By default, the `REDIS_URL` environment variable is used to setup the store. If not set, it falls back to host `127.0.0.1` port `6379`.
+Rack::Defense uses Redis to track request rates. By default, the `REDIS_URL` environment variable is used to setup
+the store. If not set, it falls back to host `127.0.0.1` port `6379`.
 The redis store can be setup with either a connection url: 
+
 ```ruby
 Rack::Defense.setup do |config|
   config.store = "redis://:p4ssw0rd@10.0.1.1:6380/15"
 end
 ```
+
 or directly with a connection object:
+
 ```ruby
 Rack::Defense.setup do |config|
   config.store = Redis.new(host: "10.0.1.1", port: 6380, db: 15)
@@ -90,7 +114,9 @@ end
 Rack::Defense can reject requests based on arbitrary properties of the request. Matching requests are filtered.
 
 ### Examples
+
 Allow only a whitelist of ips for a given path:
+
 ```ruby
 Rack::Defense.setup do |config|
   config.ban('ip_whitelist') do |req|
@@ -100,6 +126,7 @@ end
 ```
 
 Allow only requests with a known API authorization token:
+
 ```ruby
 Rack::Defense.setup do |config|
   config.ban('validate_api_token') do |req|
@@ -108,17 +135,44 @@ Rack::Defense.setup do |config|
 end
 ```
 
+The previous example uses redis to keep track of valid api tokens, but any store (database, key-value store etc.) would do here.
+
 ## Response configuration
 
-By default, Rack::Defense returns `429 Too Many Requests` and `403 Forbidden` respectively for throttled and banned requests. These responses can be fully configured in the setup:
+By default, Rack::Defense returns `429 Too Many Requests` and `403 Forbidden` respectively for throttled and banned requests.
+These responses can be fully configured in the setup:
 
 ```ruby
 Rack::Defense.setup do |config|
   config.banned_response =
     ->(env) { [404, {'Content-Type' => 'text/plain'}, ["Not Found\n"]] }
-    
   config.throttled_response =
     ->(env) { [503, {'Content-Type' => 'text/plain'}, ["Service Unavailable\n"]] }
+end
+```
+
+## Notifications
+
+You can be notified when requests are throttled or banned. The callback receives the throttled request object and data
+about the event context.
+
+For banned request callbacks, the triggered rule name is passed: 
+
+```ruby
+Rack::Defense.setup do |config|
+  config.after_ban do |req, rule|
+    logger.info "[Banned] #{rule} #{req.path} #{req.ip}"
+  end
+end
+```
+
+For throttled request callbacks, a hash having triggered rule names as keys and the corresponding throttle keys
+as values is passed. 
+
+```ruby
+Rack::Defense.setup do |config|
+  config.after_throttle do |req, rules|
+    logger.info rules.map { |e| "rule name: #{e[0]} - rule throttle key: #{e[1]}" }.join ', '
   end
 end
 ```
@@ -129,5 +183,3 @@ Licensed under the [MIT License](http://opensource.org/licenses/MIT).
 
 Copyright Sinbadsoft.
 
-
-

data/lib/rack/defense.rb

@@ -6,33 +6,53 @@ class Rack::Defense
   autoload :ThrottleCounter, 'rack/defense/throttle_counter'
 
   class Config
+    BANNED_RESPONSE = ->(_) { [403, {'Content-Type' => 'text/plain'}, ["Forbidden\n"]] }
+    THROTTLED_RESPONSE = ->(_) { [429, {'Content-Type' => 'text/plain'}, ["Retry later\n"]] }
+
     attr_accessor :banned_response
     attr_accessor :throttled_response
+
     attr_reader :bans
     attr_reader :throttles
+    attr_reader :ban_callbacks
+    attr_reader :throttle_callbacks
 
     def initialize
+      self.banned_response = BANNED_RESPONSE
+      self.throttled_response = THROTTLED_RESPONSE
       @throttles, @bans = {}, {}
-      self.banned_response = ->(env) { [403, {'Content-Type' => 'text/plain'}, ["Forbidden\n"]] }
-      self.throttled_response = ->(env) { [429, {'Content-Type' => 'text/plain'}, ["Retry later\n"]] }
-    end
+      @ban_callbacks, @throttle_callbacks = [], []
+     end
 
-    def throttle(name, max_requests, period, &block)
-      counter = ThrottleCounter.new(name, max_requests, period, store)
-      throttles[name] = lambda do |req|
+    def throttle(rule_name, max_requests, period, &block)
+      raise ArgumentError, 'rule name should not be nil' unless rule_name
+      counter = ThrottleCounter.new(rule_name, max_requests, period, store)
+      throttles[rule_name] = lambda do |req|
         key = block.call(req)
-        key && counter.throttle?(key)
+        key if key && counter.throttle?(key)
       end
     end
 
-    def ban(name, &block)
-      bans[name] = block
+    def ban(rule_name, &block)
+      raise ArgumentError, 'rule name should not be nil' unless rule_name
+      bans[rule_name] = block
+    end
+
+    def after_ban(&block)
+      ban_callbacks << block
+    end
+
+    def after_throttle(&block)
+      throttle_callbacks << block
     end
 
     def store=(value)
       value = Redis.new(url: value) if value.is_a?(String)
-      @store = SimpleDelegator::new(value) unless @store
-      @store.__setobj__(value)
+      if @store
+        @store.__setobj__(value)
+      else
+        @store = SimpleDelegator.new(value)
+      end
     end
 
     def store
@@ -45,17 +65,25 @@ class Rack::Defense
   class << self
     attr_accessor :config
 
-    def setup(&block)
+    def setup
       self.config = Config.new
       yield config
     end
 
     def ban?(req)
-      config.bans.any? { |name, filter| filter.call(req) }
+      entry = config.bans.find { |_, filter| filter.call(req) }
+      matching_rule = entry[0] if entry
+      yield config.ban_callbacks, req, matching_rule if matching_rule && block_given?
+      matching_rule
     end
 
     def throttle?(req)
-      config.throttles.any? { |name, filter| filter.call(req) }
+      matching_rules = config.throttles.
+          map { |rule_name, filter| [rule_name, filter.call(req)] }.
+          select { |e| e[1] }.
+          to_h
+      yield config.throttle_callbacks, req, matching_rules if matching_rules.any? && block_given?
+      matching_rules if matching_rules.any?
     end
   end
 
@@ -66,8 +94,25 @@ class Rack::Defense
   def call(env)
     klass, config = self.class, self.class.config
     req = ::Rack::Request.new(env)
-    return config.banned_response.call(env) if klass.ban?(req)
-    return config.throttled_response.call(env) if klass.throttle?(req)
-    @app.call(env)
+
+    if klass.ban?(req, &method(:invoke_callbacks))
+      config.banned_response.call(env)
+    elsif klass.throttle?(req, &method(:invoke_callbacks))
+      config.throttled_response.call(env)
+    else
+      @app.call(env)
+    end
+  end
+
+  private
+
+  def invoke_callbacks(callbacks, req, rule_data)
+    callbacks.each do |callback|
+      begin
+        callback.call(req, rule_data)
+      rescue
+        # mute exception
+      end
+    end
   end
 end

data/lib/rack/defense/throttle_counter.rb

@@ -1,14 +1,15 @@
 module Rack
   class Defense
     class ThrottleCounter
-
       KEY_PREFIX = 'rack-defense'
 
-      attr_accessor :logger
       attr_accessor :name
 
       def initialize(name, max_requests, time_period, store)
         @name, @max_requests, @time_period = name.to_s, max_requests.to_i, time_period.to_i
+        raise ArgumentError, 'name should not be nil or empty' if @name.empty?
+        raise ArgumentError, 'max_requests should be greater than zero' unless @max_requests > 0
+        raise ArgumentError, 'time_period should be greater than zero' unless @time_period > 0
         @store = store
       end
 
@@ -30,7 +31,6 @@ module Rack
       LUA_SCRIPT
 
       private_constant :SCRIPT
-
     end
   end
 end

data/lib/rack/defense/version.rb

@@ -1,5 +1,5 @@
 module Rack
   class Defense
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

data/spec/defense_callbacks_spec.rb

@@ -0,0 +1,60 @@
+require_relative 'spec_helper'
+
+describe 'Rack::Defense::callbacks' do
+  before do
+    @start_time = Time.utc(2015, 10, 30, 21, 0, 0)
+    @throttled = []
+    @banned = []
+
+    Rack::Defense.setup do |config|
+      config.throttle('login', 3, 10 * 1000) do |req|
+        req.ip if req.path == '/login' && req.post?
+      end
+
+      config.ban('forbidden') do |req|
+         req.path == '/forbidden'
+      end
+
+      # get notified when requests get throttled
+      config.after_throttle do |req, rules|
+        @throttled << [req, rules]
+      end
+
+      # get notified when requests get banned
+      config.after_ban do |req, rule|
+        @banned << [req, rule]
+      end
+    end
+  end
+  it 'throttle rule gets called' do
+    5.times do |offset|
+      time = @start_time + offset
+      Timecop.freeze(time) do
+        post '/login', {}, 'REMOTE_ADDR' => '192.168.0.1'
+        if offset < 3
+          assert_equal status_ok, last_response.status
+          assert_equal 0, @throttled.length
+        else
+          assert_equal status_throttled, last_response.status
+          check_callback_data(@throttled, offset - 2, { 'login' => '192.168.0.1' }, '/login')
+       end
+      end
+    end
+  end
+  it 'ban callback gets called' do
+    5.times do |i|
+      get '/forbidden'
+      assert_equal status_banned, last_response.status
+      check_callback_data(@banned, i + 1, 'forbidden', '/forbidden')
+    end
+  end
+
+  def check_callback_data(trace, matching_request_count, rule_data, req_path)
+    puts
+    assert_equal matching_request_count, trace.length
+    data = trace[-1]
+    # check callback data
+    assert_equal req_path, data[0].path
+    assert_equal rule_data, data[1]
+  end
+end

data/spec/spec_helper.rb

@@ -14,7 +14,7 @@ class MiniTest::Spec
   def app
     Rack::Builder.new {
       use Rack::Defense
-      run ->(env) { [200, {}, ['Hello World']] }
+      run ->(_) { [200, {}, ['Hello World']] }
     }.to_app
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-defense
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Chaker Nakhli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-10 00:00:00.000000000 Z
+date: 2014-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -107,6 +107,7 @@ files:
 - lib/rack/defense/throttle_counter.rb
 - lib/rack/defense/version.rb
 - spec/defense_ban_spec.rb
+- spec/defense_callbacks_spec.rb
 - spec/defense_config_spec.rb
 - spec/defense_throttle_spec.rb
 - spec/spec_helper.rb
@@ -137,8 +138,9 @@ signing_key:
 specification_version: 4
 summary: Throttle and filter requests
 test_files:
-- spec/spec_helper.rb
-- spec/throttle_counter_spec.rb
-- spec/defense_config_spec.rb
 - spec/defense_ban_spec.rb
+- spec/defense_callbacks_spec.rb
+- spec/defense_config_spec.rb
 - spec/defense_throttle_spec.rb
+- spec/spec_helper.rb
+- spec/throttle_counter_spec.rb