From 0faab213382426afd124743267b9e5562232efc6 Mon Sep 17 00:00:00 2001
From: Aaron Suggs <aaron@ktheory.com>
Date: Sat, 28 Jul 2012 22:10:08 -0400
Subject: [PATCH] More docs

---
 README.md | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 24e76e5..691a2a9 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Thottle state is stored in a configurable cache (e.g. `Rails.cache`), presumably
 
 ## Installation
 
-Add "rack-attack" to your Gemfile or run
+Add the [rack-attack](http://rubygems.org/gems/rack-attack) gem to your Gemfile or run
 
     gem install rack-attack
 
@@ -38,6 +38,11 @@ The Rack::Attack middleware examines each request against *whitelists*, *blackli
 
 ## Usage
 
+Define blacklists, throttles, and whitelists.
+Note that `req` is a [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) object.
+
+### Blacklists
+
     # Block requests from 1.2.3.4
     Rack::Attack.blacklist('block 1.2.3.4') do |req|
       # Request are blocked if the return value is truthy
@@ -49,6 +54,8 @@ The Rack::Attack middleware examines each request against *whitelists*, *blackli
       req.post? && request.path == '/login' && req.user_agent == 'BadUA'
     end
 
+### Throttles
+
     # Throttle requests to 5 requests per second per ip
     Rack::Attack.throttle('req/ip', :limit => 5, :period => 1.second) do |req|
       # If the return value is truthy, the cache key for "rack::attack:req/ip:#{req.ip}" is incremented and checked.
@@ -61,6 +68,8 @@ The Rack::Attack middleware examines each request against *whitelists*, *blackli
       req.post? && request.path == '/login' && req.params['email']
     end
 
+### Whitelists
+
     # Always allow requests from localhost
     # (blacklist & throttles are skipped)
     Rack::Attack.whitelist('allow from localhost') do |req|
@@ -68,7 +77,21 @@ The Rack::Attack middleware examines each request against *whitelists*, *blackli
       '127.0.0.1' == req.ip
     end
 
-Note that `req` is a [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) object.
+## Responses
+
+Customize the response of throttled requests using an object that adheres to the [Rack app interface](http://rack.rubyforge.org/doc/SPEC.html).
+
+    Rack:Attack.throttled_response = lambda do |env|
+      env['rack.attack.throttled'] # name and other data about the matched throttle
+      [ 503, {}, ['Throttled']]
+    end
+
+Similarly for blacklisted responses:
+
+    Rack:Attack.blacklisted_response = lambda do |env|
+      env['rack.attack.blacklisted'] # name of the matched blacklist
+      [ 503, {}, ['Blocked']]
+    end
 
 ## Logging & Instrumentation
 
@@ -84,4 +107,8 @@ less on short-term, one-off hacks to block a particular attack.
 
 Rack::Attack complements `iptables` and nginx's [limit_zone module](http://wiki.nginx.org/HttpLimitZoneModule).
 
+## Thanks
+
+Thanks to [Kickstarter](https://github.com/kickstarter) for sponsoring Rack::Attack development
+
 [![Travis CI](https://secure.travis-ci.org/ktheory/rack-attack.png)](http://travis-ci.org/ktheory/rack-attack)