Provided by: libcgi-application-plugin-ratelimit-perl_1.0-3_all 
NAME
CGI::Application::Plugin::RateLimit - limits runmode call rate per user
SYNOPSIS
use CGI::Application::Plugin::RateLimit;
sub setup {
...
# call this in your setup routine to set
my $rate_limit = $self->rate_limit();
# set the database handle to use
$rate_limit->dbh($dbh);
# set the table name to use for storing hits, the default is
# 'rate_limit_hits'
$rate_limit->table('rate_limit_hits');
# keep people from calling 'send' more often than 5 times in 10
# minutes and 'list' more often than once every 5 seconds.
$rate_limit->protected_modes(send => {timeframe => '10m',
max_hits => 5
},
list => {timeframe => '5s',
max_hits => 1
});
# you can also protect abstract actions, for example to prevent a
# flood of failed logins
$rate_limit->protected_actions(failed_login => {timeframe => '10s',
max_hits => 2
});
# call this runmode when a violation is detected
$rate_limit->violation_mode('too_fast_buddy');
# or, run this callback
$rate_limit->violation_callback(sub { die(...) });
# override the default identity function
# ($ENV{REMOTE_USER} || $ENV{REMOTE_IP})
$rate_limit->identity_callback(sub { ... });
}
# record a hit for an action (not needed for run-modes which are
# handled automatically)
$rate_limit->record_hit(action => 'failed_login');
# check for a violation on an action and handle
return $self->slow_down_buddy
if( $rate_limit->check_violation(action => 'failed_login') );
# revoke the most recent hit for this user, preventing it from
# counting towards a violation
$rate_limit->revoke_hit();
# examine the violation in violation_mode or violation_callback:
$mode = $rate_limit->violated_mode;
$action = $rate_limit->violated_action;
$limits = $rate_limit->violated_limits;
DESCRIPTION
This module provides protection against a user calling a runmode too frequently. A
typical use-case might be a contact form that sends email. You'd like to allow your users
to send you messages, but thousands of messages from a single user would be a problem.
This module works by maintaining a database of hits to protected runmodes. It then checks
this database to determine if a new hit should be allowed based on past activity by the
user. The user's identity is, by default, tied to login (via REMOTE_USER) or IP address
(via REMOTE_IP) if login info is not available. You may provide your own identity
function via the identity_callback() method.
To use this module you must create a table in your database with the following schema
(using MySQL-syntax, although other DBs may work as well with minor alterations):
CREATE TABLE rate_limit_hits (
user_id VARCHAR(255) NOT NULL,
action VARCHAR(255) NOT NULL,
timestamp UNSIGNED INTEGER NOT NULL,
INDEX (user_id, action, timestamp)
);
You may feel free to vary the storage-type and size of user_id and action to match your
usage. For example, if your identity_callback() always returns an integer you could make
user_id an integer column.
This table should be periodically cleared of old data. Anything older than the maximum
timeframe being used can be safely deleted.
IMPORTANT NOTE: The protection offered by this module is not perfect. Identifying a user
on the internet is very hard and a sophisticated attacker can work around these checks, by
switching IPs or automating login creation.
INTERFACE
The object returned from calling "$self->rate_limit" on your CGI::App object supports the
following method calls:
dbh
$rate_limit->dbh($dbh);
Call this to set the database handle the object should use. Must be set in setup().
table
$rate_limit->table('some_table_name');
Call this to determine the table to be used to store and lookup hits. The default is
'rate_limit_hits' if not set. See the DESCRIPTION section for the required table schema.
protected_modes
$rate_limit->protected_modes(send => {timeframe => '10m',
max_hits => 5
},
list => {timeframe => '5s',
max_hits => 1
});
Takes a list of key-value pairs describing the modes to protect. Keys are names of run-
modes. Values are hashes with the following keys:
timeframe - the timeframe to be considered for violations. Values
must be numbers followed by either 's' for seconds, 'm' for minutes
or 'h' for hours.
max_hits - how many hits to allow in the specified timeframe before
triggering a violation.
protected_actions
$rate_limit->protected_actions(failed_login => {timeframe => '10s',
max_hits => 2
});
Specifies non-run-mode actions to protect. These are arbitrary keys you can use with
record_hit() and check_violation(). Takes the same data-structure as protected_modes().
violation_mode
$rate_limit->violation_mode('too_fast_buddy');
Call to set a run-mode to call when a violation is triggered. Either this or
violation_callback must be set.
violation_callback
$rate_limit->violation_callback(sub { ... });
Callback to call when a violation is detected. Should either throw an exception or return
the run-mode to run. Called with the CGI::App object as its sole parameter.
identity_callback
$rate_limit->identity_callback(sub { ... });
Call this to provide a customized mechanism for determining the identity of the user. The
default is:
sub { $ENV{REMOTE_USER} || $ENV{REMOTE_IP} }
You might consider adding in session-ID or a hook to your authentication system if it
doesn't use REMOTE_USER. Whatever you write should return a single scalar which is
expected to be unique to each user.
record_hit
$rate_limit->record_hit(action => 'failed_login');
Record a hit for an arbitrary action. This is not needed for run-mode protection. Takes
the action name as an argument, which must match an action registered with
protected_actions().
check_violation
return $self->slow_down_buddy
if( $rate_limit->check_violation(action => 'failed_login') );
Checks for a violation of a protected action. This is not needed for run-mode protection.
Takes the action name as an argument, which must match an action registered with
protected_actions().
Returns 1 if a violation took place, 0 otherwise.
revoke_hit
$rate_limit->revoke_hit();
Revokes the last hit for this user. You might use this to prevent validation errors from
counting against a user, for example.
violated_mode
$mode = $rate_limit->violated_mode;
Returns the mode for the last violation, or undef if an action caused the violation.
violated_action
$mode = $rate_limit->violated_action;
Returns the action for the last violation, or undef if an action caused the violation.
violated_limits
$limits = $rate_limit->violated_limits;
Returns the hash-ref passed to protected_actions() or protected_modes() for the violated
mode/action.
DATABASE SUPPORT
I've tested this module with MySQL and SQLite. I think it's likely to work with many
other databases - please let me know if you try one.
SUPPORT
Please send questions and suggestions about this module to the CGI::Application mailing-
list. To join the mailing list, simply send a blank message to:
cgiapp-subscribe@lists.erlbaum.net
VERSION CONTROL
This module is in a public Subversion repository at SourceForge here:
https://svn.sourceforge.net/svnroot/html-template/trunk/CGI-Application-Plugin-RateLimit
BUGS
I know of no bugs. If you find one, let me know by filing a report on http://rt.cpan.org.
Failing that, you can email me at sam@tregar.com. Please include the version of the
module you're using and small test case demonstrating the problem.
AUTHOR
Sam Tregar, sam@plusthree.com
COPYRIGHT AND LICENSE
Copyright (C) 2006 by Sam Tregar
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of
Perl 5 you may have available.