README.md in improved-rack-throttle-0.7.0 vs README.md in improved-rack-throttle-0.7.1
- old
+ new
@@ -1,14 +1,17 @@
HTTP Request Rate Limiter for Rack Applications
===============================================
-This is [Rack][] middleware that provides logic for rate-limiting incoming
+[](https://codeclimate.com/github/bensomers/improved-rack-throttle)
+[](https://gemnasium.com/bensomers/improved-rack-throttle)
+
+This is a [Rack][] middleware that provides logic for rate-limiting incoming
HTTP requests to Rack applications. You can use `Rack::Throttle` with any
Ruby web framework based on Rack, including with Ruby on Rails 3.0 and with
Sinatra.
-* <http://github.com/datagraph/rack-throttle>
+* <http://github.com/bensomers/improved-rack-throttle>
Features
--------
* Throttles a Rack application by enforcing a minimum time interval between
@@ -24,11 +27,10 @@
multiple web servers.
* Compatible with the [gdbm][] binding included in Ruby's standard library.
* Compatible with the [memcached][], [memcache-client][], [memcache][] and
[redis][] gems.
* Compatible with [Heroku][]'s [memcached add-on][Heroku memcache]
- (currently available as a free beta service).
Examples
--------
### Adding throttling to a Rails 3.x application
@@ -69,10 +71,14 @@
### Allowing a maximum of 1,000 requests per day
use Rack::Throttle::Daily, :max => 1000
+### Allowing 1 request per second, with bursts of up to 5 requests
+
+ use Rack::Throttle::SlidingWindow, :average => 1, :burst => 5
+
### 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
@@ -100,11 +106,11 @@
use Rack::Throttle::Interval, :rules => {:url => /api/, :method => :post}
Throttling Strategies
---------------------
-`Rack::Throttle` supports three built-in throttling strategies:
+`Rack::Throttle` supports four 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
@@ -112,10 +118,16 @@
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).
+* `Rack::Throttle::SlidingWindow`: Throttles the application by defining
+ an average request rate, and a burst allowance that clients can hit
+ (as long as they stay within the average). By default, this is 1
+ request per second, with bursts of up to 5 requests at a time. Users
+ who exceed the average and who have used up their burst will have all
+ of their requests denied until they comply with the policy.
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
@@ -123,11 +135,11 @@
`Rack::Throttle::Limiter` base class directly.
Scoping Rules
-------------
Rack::Throttle ships with a Rack::Throttle::Matcher base class, and three
-implementations of it. Rack::Throttle::UrlMatcher and
+implementations. Rack::Throttle::UrlMatcher and
Rack::Throttle::UserAgentMatcher allow you to pass in regular expressions
for request path and user agent, while Rack::Throttle::MethodMatcher
will filter by request method when passed a Symbol :get, :post, :put, or
:delete. These rules are additive, so you can throttle just POST
requests to your '/login' page, for example.
@@ -140,11 +152,11 @@
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 a throttling strategy implementation and
+name, you can subclass a throttling strategy implementation and
override the `#client_identifier` method.
HTTP Response Codes and Headers
-------------------------------
@@ -174,17 +186,22 @@
status code by passing in a `:code => 503` option when constructing a
`Rack::Throttle::Limiter` instance.
Documentation
-------------
-OUT OF DATE
+UNDER DEVELOPMENT
-<http://datagraph.rubyforge.org/rack-throttle/>
+<http://rubydoc.info/gems/improved-rack-throttle>
* {Rack::Throttle}
* {Rack::Throttle::Interval}
* {Rack::Throttle::Daily}
* {Rack::Throttle::Hourly}
+ * {Rack::Throttle::SlidingWindow}
+ * {Rack::Throttle::Matcher}
+ * {Rack::Throttle::MethodMatcher}
+ * {Rack::Throttle::UrlMatcher}
+ * {Rack::Throttle::UserAgentMatcher}
Dependencies
------------
* [Rack](http://rubygems.org/gems/rack) (>= 1.0.0)