Cgi::application::plugin::ratelimit 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.