start POD

5 files changed, 191 insertions, 16 deletions

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
 
diff --git a/lib/Plack/Middleware/Throttle/Daily.pm b/lib/Plack/Middleware/Throttle/Daily.pm
index d28d1d7..378ce17 100644
--- a/lib/Plack/Middleware/Throttle/Daily.pm
+++ b/lib/Plack/Middleware/Throttle/Daily.pm
@@ -15,3 +15,45 @@ sub reset_time {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Plack::Middleware::Throttle::Daily - A Plack Middleware for rate-limiting incoming HTTP requests.
+
+=head1 SYNOPSIS
+
+  my $handler = builder {
+    enable "Throttle::Daily",
+        max     => 2,
+        backend => Plack::Middleware::Throttle::Backend::Hash->new();
+    sub { [ '200', [ 'Content-Type' => 'text/html' ], ['hello world'] ] };
+  };
+
+=head1 DESCRIPTION
+
+How many request an host can do in one day.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<max>
+
+How many requets can be done in one day.
+
+=back
+
+=head1 AUTHOR
+
+franck cuny E<lt>franck@lumberjaph.netE<gt>
+
+=head1 SEE ALSO
+
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
+
diff --git a/lib/Plack/Middleware/Throttle/Hourly.pm b/lib/Plack/Middleware/Throttle/Hourly.pm
index 818d70b..84b3d6d 100644
--- a/lib/Plack/Middleware/Throttle/Hourly.pm
+++ b/lib/Plack/Middleware/Throttle/Hourly.pm
@@ -15,3 +15,44 @@ sub reset_time {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Plack::Middleware::Throttle::Hourly - A Plack Middleware for rate-limiting incoming HTTP requests.
+
+=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
+
+How many request an host can do in one hour.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<max>
+
+How many requets can be done in one hour.
+
+=back
+
+=head1 AUTHOR
+
+franck cuny E<lt>franck@lumberjaph.netE<gt>
+
+=head1 SEE ALSO
+
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
diff --git a/lib/Plack/Middleware/Throttle/Interval.pm b/lib/Plack/Middleware/Throttle/Interval.pm
index 3e61220..cd40fde 100644
--- a/lib/Plack/Middleware/Throttle/Interval.pm
+++ b/lib/Plack/Middleware/Throttle/Interval.pm
@@ -29,3 +29,45 @@ sub reset_time {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Plack::Middleware::Throttle::Interval - A Plack Middleware for rate-limiting incoming HTTP requests.
+
+=head1 SYNOPSIS
+
+  my $handler = builder {
+    enable "Throttle::Interval",
+        min     => 2,
+        backend => Plack::Middleware::Throttle::Backend::Hash->new();
+    sub { [ '200', [ 'Content-Type' => 'text/html' ], ['hello world'] ] };
+  };
+
+=head1 DESCRIPTION
+
+How many request an host can do between an interval of time (in seconds).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<in>
+
+How many requets can be done in an interval of time.
+
+=back
+
+=head1 AUTHOR
+
+franck cuny E<lt>franck@lumberjaph.netE<gt>
+
+=head1 SEE ALSO
+
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
+
diff --git a/lib/Plack/Middleware/Throttle/Limiter.pm b/lib/Plack/Middleware/Throttle/Limiter.pm
index 4194fe4..4a8cd7f 100644
--- a/lib/Plack/Middleware/Throttle/Limiter.pm
+++ b/lib/Plack/Middleware/Throttle/Limiter.pm
@@ -36,3 +36,25 @@ sub add_headers {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Plack::Middleware::Throttle - A Plack Middleware for rate-limiting incoming HTTP requests.
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+=head1 AUTHOR
+
+franck cuny E<lt>franck@lumberjaph.netE<gt>
+
+=head1 SEE ALSO
+
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut