The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-1.001003
River stage one • 1 direct dependent • 1 total dependent
++
/ App::ZofCMS::Plugin::FloodControl

NAME

App::ZofCMS::Plugin::FloodControl - plugin for protecting forms and anything else from floods (abuse)

SYNOPSIS

In your Main Config File or ZofCMS Template file:

    plug_flood_control => {
        dsn             => "DBI:mysql:database=test;host=localhost",
        user            => 'test',
        pass            => 'test',
        # everything below is optional
        opt             => { RaiseError => 1, AutoCommit => 1 },
        create_table    => 0,
        limit           => 2,
        timeout         => 600,
        table           => 'flood_control',
        run             => 0,
        trigger         => 'plug_flood',
        cell            => 'q',
        t_key           => 'plug_flood',
        flood_id        => 'flood',
        flood_code      => sub {
            my ( $template, $query, $config ) = @_;
            kill_damn_flooders();
        },
        no_flood_code   => sub {
            my ( $template, $query, $config ) = @_;
            hug_the_user();
        },
    }

In your HTML::Template Template:

    <tmpl_if name='plug_flood'>
        STOP FLOODING, ASSHOLE!
    <tmpl_else>
        <form ....
        .../form>
    </tmpl_if>

Plugin needs an SQL table to operate. You can either create it by hand or set the create_table option to a true value once so plugin could create the table automatically. The needed table needs to have these three columns:

    CREATE TABLE flood_table (host VARCHAR(250), time VARCHAR(10), id VARCHAR(5));

The value type of the id column can be different depending on what flood_id arguments you'd use (see docs below for more).

DESCRIPTION

The module is a plugin for App::ZofCMS. It provides means to detect flood (abuse) and react accordingly depending on whether or not flood was detected.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

plugins

    plugins => [ qw/FloodControl/ ],

You obviously need to the add the plugin in the list of plugins to execute. Along with this plugin you would probably want to use something like App::ZofCMS::Plugin::FormChecker and App::ZofCMS::Plugin::DBI

plug_flood_control

    plug_flood_control => {
        dsn             => "DBI:mysql:database=test;host=localhost",
        user            => 'test',
        pass            => 'test',
        # everything below is optional
        opt             => { RaiseError => 1, AutoCommit => 1 },
        create_table    => 0,
        limit           => 2,
        timeout         => 600,
        table           => 'flood_control',
        run             => 0,
        trigger         => 'plug_flood',
        cell            => 'q',
        t_key           => 'plug_flood',
        flood_id        => 'flood',
        flood_code      => sub {
            my ( $template, $query, $config ) = @_;
            kill_damn_flooders();
        },
        no_flood_code   => sub {
            my ( $template, $query, $config ) = @_;
            hug_the_user();
        },
    }

    plug_flood_control => sub {
        my ( $t, $q, $config ) = @_;
        return {
            dsn             => "DBI:mysql:database=test;host=localhost",
            user            => 'test',
            pass            => 'test',
        };
    }

Plugin uses plug_flood_control first-level key that can be specified in either (or both) Main Config File or ZofCMS Template file. The key takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_flood_control as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Tempalate hashref, query parameters hashref and App::ZofCMS::Config object. If the keys of that hashref are specified in both files will take their values from ZofCMS Template. Most of these keys are optional with sensible defaults. Possible keys/values are as follows:

dsn

    dsn => "DBI:mysql:database=test;host=localhost",

Mandatory. Specifies the "DSN" for DBI module. See DBI's docs for connect_cached() method for more info on this one.

user

    user => 'test',

Mandatory. Specifies your username for the SQL database.

pass

    pass => 'test',

Mandatory. Specifies your password for the SQL database.

opt

    opt => { RaiseError => 1, AutoCommit => 1 },

Optional. Takes a hashref as a value. Specifies the additional options for DBI's connect_cached() method. See DBI's docs for connect_cached() method for more info on this one. Defaults to: { RaiseError => 1, AutoCommit => 1 }

table

    table => 'flood_control',

Optional. Takes a string as a value that represents the name of the table in which to store flood data. Defaults to: flood_control

create_table

    create_table => 0,

Optional. Takes either true or false values. When set to a true value will automatically create the table that is needed for the plugin. You can create the table manually, its format is described in the SYNOPSIS section above. Defaults to: 0

limit

    limit => 2,

Optional. Specifies the "flood limit". Takes a positive integer value that is the number of times the plugin will be triggered in timeout (see below) seconds before it will think we are being abused. Defaults to: 2

timeout

    timeout => 600,

Optional. Takes a positive integer value. Specifies timeout in seconds after which the plugin will forget that a certain user triggered it. In other words, if the plugin is triggered when someone submits the form and timeout is set to 600 and limit is set to 2 then the user would be able to submit the form only twice every 10 minutes. Defaults to: 600

trigger

    trigger => 'plug_flood',

Optional. Takes a string as a value that names the key in a cell (see below). Except for when the cell is set to q, the value referenced by the key must contain a true value in order for the plugin to trigger (to run). Defaults to: plug_flood

cell

    cell => 'q',

Optional. The plugin can be triggered either from query, {t} special key, {d} ZofCMS Template special key, or any first-level ZofCMS Template key (also, see run option below). The value of the cell key specifies where the plugin will look for the trigger (see above). Possible values for cell key are: q (query), d ({d} key), t ({t} key) or empty string (first-level ZofCMS Template key). For every cell value but the q, the trigger (i.e. the key referenced by the trigger argument) must be set to a true value in order for the plugin to trigger. When cell is set to value q, then the query parameter referenced by trigger must have length() in order for the plugin to trigger. Defaults to: q

run

    run => 0,

Optional. An alternative to using cell and trigger arguments you can set (e.g. dynamically with some other plugin) the run argument to a true value. Takes either true or false values. When set to a true value plugin will "trigger" (check for floods) without any consideration to cell and trigger values. Defaults to: 0

t_key

    t_key => 'plug_flood',

Optional. If plugin sees that the user is flooding, it will set t_key in ZofCMS Template {t} special key. Thus you can display appropriate messages using <tmpl_if name="">. Defaults to: plug_flood

flood_id

    flood_id => 'flood',

Optional. You can use the same table to control various pages or forms from flood independently by setting flood_id to different values for each of them. Defaults to: flood

flood_code

    flood_code => sub {
        my ( $template, $query, $config ) = @_;
        kill_damn_flooders();
    },

Optional. Takes a subref as a value. This sub will be run if plugin thinks that the user is flooding. The @_ will contain (in that order) ZofCMS Template hashref, query parameters hashref where keys are params' names and values are their values and App::ZofCMS::Config object. By default is not specified.

no_flood_code

    no_flood_code   => sub {
        my ( $template, $query, $config ) = @_;
        hug_the_user();
    },

Optional. Takes a subref as a value. This is the opposite of flood_code. This sub will be run if plugin thinks that the user is NOT flooding. The @_ will contain (in that order) ZofCMS Template hashref, query parameters hashref where keys are params' names and values are their values and App::ZofCMS::Config object. By default is not specified.

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.