The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Cerberus-0.11
River stage one • 2 direct dependents • 2 total dependents
++
/ App::Cerberus

NAME

App::Cerberus - A pluggable Perl web service to preprocess web requests. Plugins can add geo, timezone and browser metadata, and throttle request rate.

VERSION

version 0.11

DESCRIPTION

There is a bunch of things we want to know about our web users, such as:

  • Geo-location

  • Time zone

  • User-agent info

  • Are they a spider?

  • Are they making too many requests? Should we throttle them?

To get all the above information reliably can easily consume 20MB+ of memory in every web server process.

App::Cerberus packages up all this functionality into a simple web service (using Plack), freeing up your web processes to deal with just your own code.

A query to App::Cerberus is a simple HTTP GET, and the response is JSON.

PLUGINS

App::Cerberus::Plugin::GeoIP

Uses Geo::IP with the GeoLite City database to provide geo-location at the city level.

For instance:

    "geo": {
        "area_code": 201,
        "longitude": "-74.0781",
        "country_name": "United States",
        "region_name": "New Jersey",
        "country_code": "US",
        "region": "NJ",
        "city": "Jersey City",
        "postal_code": "07304",
        "latitude": "40.7167"
    }

App::Cerberus::Plugin::TimeZone

Uses Time::OlsonTZ::Data to provide the current timezone for the user, and it's offset from GMT.

For instance:

    "tz": {
        "short_name": "EDT",
        "name": "America/New_York",
        "dst": "1",
        "gmt_offset": "-14400"
    }

The GeoIP plugin must be run before the TimeZone plugin.

App::Cerberus::Plugin::BrowserDetect

Uses HTTP::BrowserDetect to provide data about the user agent and recognises the most well known robots.

For instance:

    "ua": {
        "is_robot": 0,
        "is_mobile": 0,
        "is_tablet": 1,
        "version": {
            "minor": ".1",
            "full": 5.1,
            "major": "5"
        },
        "browser": "safari",
        "device": "ipad",
        "browser_properties": [
            "ios",
            "iphone",
            "ipod",
            "mobile",
            "safari",
            "device"
        ],
        "os": "iOS"
    }

App::Cerberus::Plugin::Throttle

Set per-second, per-minute, per-hour, per-day and per-month request limits. Different limits can be applied to different IP ranges.

For instance:

    "throttle": {
        "range":         "google",
        "reason":        "second",
        "sleep":         10,
        "request_count": 12
    }

INSTALLING CERBERUS

App::Cerberus can be installed with your favourite cpan installer, eg:

    cpanm App::Cerberus

The only exception to this is that the Geo::IP module should be properly installed first, as it requires some manual work to make it use the C API.

See "INSTALLING GEO::IP" in App::Cerberus::Plugin::GeoIP for instructions.

CONFIGURING CERBERUS

cerberus.pl requires a YAML config file, eg:

    cerberus --conf /path/to/cerberus.yml

You can find an example cerberus.yml here: http://github.com/downloads/clintongormley/App-Cerberus/cerberus.yml

The config file has two sections:

plack

This lists any command line options that should be passed to plackup, eg:

    plack:
        - port:                 5001
        - server:               Starman
        - workers:              2
        - daemonize

plugins

This lists the plugins that should be loaded, and passes any specified parameters to init(). Plugins are run in the order specified:

    plugins:
      - GeoIP:                  /opt/geoip/GeoLiteCity.dat
      - TimeZone
      - BrowserDetect
      - Throttle:
            store:
                Memcached:
                    namespace:  cerberus
                    servers:
                        -       localhost:11211

            second_penalty:     5
            ranges:
                default:
                    ips:        0.0.0.0/0
                    limit:
                                - 20 per second
                                - 100 per minute

See each plugin for details of the accepted parameters.

RUNNING CERBERUS

    cerberus --conf /path/to/cerberus.yml

See cerberus.pl for more options.

SEE ALSO

App::Cerberus::Client
Dancer::Plugin::Cerberus

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc App::Cerberus

You can also look for information at:

AUTHOR

Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Clinton Gormley.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.