/ 
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.