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

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
    <http://www.maxmind.com/app/geolite> 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": 1,
            "version": {
                "minor": ".1",
                "full": 5.1,
                "major": "5"
            },
            "browser": "safari",
            "device": "iphone",
            "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:

    *   GitHub

        <http://github.com/clintongormley/App-Cerberus>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/App-Cerberus>

    *   Search MetaCPAN

        <https://metacpan.org/module/App::Cerberus>

AUTHOR
    Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 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.