From a4659c4df26f36f806ad24d7524c264a236d7bbb Mon Sep 17 00:00:00 2001
From: franck cuny <franck@lumberjaph.net>
Date: Thu, 1 Apr 2010 17:24:06 +0200
Subject: start POD

---
 lib/Plack/Middleware/Throttle.pm | 60 +++++++++++++++++++++++++++++-----------
 1 file changed, 44 insertions(+), 16 deletions(-)

(limited to 'lib/Plack/Middleware/Throttle.pm')

diff --git a/lib/Plack/Middleware/Throttle.pm b/lib/Plack/Middleware/Throttle.pm
index fe1fae1..8ba1537 100644
--- a/lib/Plack/Middleware/Throttle.pm
+++ b/lib/Plack/Middleware/Throttle.pm
@@ -127,43 +127,71 @@ Plack::Middleware::Throttle - A Plack Middleware for rate-limiting incoming HTTP
 
 =head1 SYNOPSIS
 
+  my $handler = builder {
+    enable "Throttle::Hourly",
+        max     => 2,
+        backend => Plack::Middleware::Throttle::Backend::Hash->new();
+    sub { [ '200', [ 'Content-Type' => 'text/html' ], ['hello world'] ] };
+  };
+
 =head1 DESCRIPTION
 
-Set a limit on how many requests per hour is allowed on your API. In of a authorized request, 3 headers are added:
+This is a C<Plack> middleware that provides logic for rate-limiting incoming
+HTTP requests to Rack applications.
+
+This middleware provides three ways to handle throttling on incoming requests :
 
-=over 2
+=over 4
 
-=item B<X-RateLimit-Limit>
+=item B<Hourly>
 
-How many requests are authorized by hours
+How many requests an host can do in one hour. The counter is reseted each hour.
 
-=item B<X-RateLimit-Remaining>
+=item B<Daily>
 
-How many remaining requests
+How many requets an host can do in one hour. The counter is reseted each day.
 
-=item B<X-RateLimit-Reset>
+=item B<Interval>
 
-When will the counter be reseted (in epoch)
+Which interval of time an host must respect between two request.
 
 =back
 
-=head2 VARIABLES
+=head1 OPTIONS
 
 =over 4
 
+=item B<code>
+
+HTTP code returned in the response when the limit have been exceeded. By default 503.
+
+=item B<message>
+
+HTTP message returned in the response when the limit have been exceeded. By defaylt "Over rate limit"
+
 =item B<backend>
 
-Which backend to use. Currently only Hash and Redis are supported. If no
-backend is specified, Hash is used by default. Backend must implement B<set>,
-B<get> and B<incr>.
+A cache object to store sessions informations.
 
-=item B<code>
+  backend => Redis->new(server => '127.0.0.1:6379');
 
-HTTP code that will be returned when too many connections have been reached.
+or
 
-=item B<message>
+  backend => Cache::Memcached->new(servers => ["10.0.0.15:11211", "10.0.0.15:11212"]);
+
+The cache object must implement B<get>, B<set> and B<incr> methods. By default, you can use C<Plack::Middleware::Throttle::Backend::Hash>.
+
+=item B<key_prefix>
+
+Key to prefix sessions entry in the cache
+
+=item B<white_list>
+
+An arrayref of hosts to put in a white list.
+
+=item B<black_list>
 
-HTTP message that will be returned when too many connections have been reached.
+An arrayref of hosts to put in a black list.
 
 =back
 
-- 
cgit v1.2.3