README in rack-throttle-0.2.0 vs README in rack-throttle-0.3.0

@@ -9,12 +9,14 @@
 * <http://github.com/datagraph/rack-throttle>
 
 Features
 --------
 
-* Throttles a Rack application by enforcing a minimum interval (by default,
-  1 second) between subsequent HTTP requests from a particular client.
+* Throttles a Rack application by enforcing a minimum time interval between
+  subsequent HTTP requests from a particular client, as well as by defining
+  a maximum number of allowed HTTP requests per a given time period (hourly
+  or daily).
 * Compatible with any Rack application and any Rack-based framework.
 * Stores rate-limiting counters in any key/value store implementation that
   responds to `#[]`/`#[]=` (like Ruby's hashes) or to `#get`/`#set` (like
   memcached or Redis).
 * Compatible with the [gdbm][] binding included in Ruby's standard library.
@@ -32,40 +34,80 @@
 
     use Rack::Throttle::Interval
 
     run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }
 
-### Enforcing a 3-second interval between requests
+### Enforcing a minimum 3-second interval between requests
 
     use Rack::Throttle::Interval, :min => 3.0
 
-### Using GDBM to store rate-limiting counters
+### Allowing a maximum of 100 requests per hour
 
+    use Rack::Throttle::Hourly,   :max => 100
+
+### Allowing a maximum of 1,000 requests per day
+
+    use Rack::Throttle::Daily,    :max => 1000
+
+### Combining various throttling constraints into one overall policy
+
+    use Rack::Throttle::Daily,    :max => 1000  # requests
+    use Rack::Throttle::Hourly,   :max => 100   # requests
+    use Rack::Throttle::Interval, :min => 3.0   # seconds
+
+### Storing the rate-limiting counters in a GDBM database
+
     require 'gdbm'
+    
     use Rack::Throttle::Interval, :cache => GDBM.new('tmp/throttle.db')
 
-### Using Memcached to store rate-limiting counters
+### Storing the rate-limiting counters on a Memcached server
 
     require 'memcached'
+    
     use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
 
-### Using Redis to store rate-limiting counters
+### Storing the rate-limiting counters on a Redis server
 
     require 'redis'
+    
     use Rack::Throttle::Interval, :cache => Redis.new, :key_prefix => :throttle
 
+Throttling Strategies
+---------------------
+
+`Rack::Throttle` supports three built-in throttling strategies:
+
+* `Rack::Throttle::Interval`: Throttles the application by enforcing a
+  minimum interval (by default, 1 second) between subsequent HTTP requests.
+* `Rack::Throttle::Hourly`: Throttles the application by defining a
+  maximum number of allowed HTTP requests per hour (by default, 3,600
+  requests per 60 minutes, which works out to an average of 1 request per
+  second).
+* `Rack::Throttle::Daily`: Throttles the application by defining a
+  maximum number of allowed HTTP requests per day (by default, 86,400
+  requests per 24 hours, which works out to an average of 1 request per
+  second).
+
+You can fully customize the implementation details of any of these strategies
+by simply subclassing one of the aforementioned default implementations.
+And, of course, should your application-specific requirements be
+significantly more complex than what we've provided for, you can also define
+entirely new kinds of throttling strategies by subclassing the
+`Rack::Throttle::Limiter` base class directly.
+
 HTTP Client Identification
 --------------------------
 
 The rate-limiting counters stored and maintained by `Rack::Throttle` are
 keyed to unique HTTP clients.
 
 By default, HTTP clients are uniquely identified by their IP address as
 returned by `Rack::Request#ip`. If you wish to instead use a more granular,
 application-specific identifier such as a session key or a user account
-name, you need only subclass `Rack::Throttle::Interval` and override the
-`#client_identifier` method.
+name, you need only subclass a throttling strategy implementation and
+override the `#client_identifier` method.
 
 HTTP Response Codes and Headers
 -------------------------------
 
 ### 403 Forbidden (Rate Limit Exceeded)
@@ -79,15 +121,15 @@
 This indicates an error on the client's part in exceeding the rate limits
 outlined in the acceptable use policy for the site, service, or API.
 
 ### 503 Service Unavailable (Rate Limit Exceeded)
 
-However, there is an unfortunately widespread practice of instead returning
-a "503 Service Unavailable" response when a client exceeds the set rate
-limits. This is actually technically incorrect because it indicates an
-error on the server's part, which is certainly not the case with rate
-limiting - it was the client that committed the oops, not the server.
+However, there exists a widespread practice of instead returning a "503
+Service Unavailable" response when a client exceeds the set rate limits.
+This is technically dubious because it indicates an error on the server's
+part, which is certainly not the case with rate limiting - it was the client
+that committed the oops, not the server.
 
 An HTTP 503 response would be correct in situations where the server was
 genuinely overloaded and couldn't handle more requests, but for rate
 limiting an HTTP 403 response is more appropriate. Nonetheless, if you think
 otherwise, `Rack::Throttle` does allow you to override the returned HTTP
@@ -127,13 +169,14 @@
 Alternatively, you can download the latest development version as a tarball
 as follows:
 
     % wget http://github.com/datagraph/rack-throttle/tarball/master
 
-Author
-------
+Authors
+-------
 
 * [Arto Bendiken](mailto:[e-mail]) - <http://ar.to/>
+* [Brendon Murphy](mailto:[e-mail]>) - <http://www.techfreak.net/>
 
 License
 -------
 
 `Rack::Throttle` is free and unencumbered public domain software. For more