Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A pluggable Perl web service to preprocess web requests. Plugins can add geo, timezone and browser metadata, and throttle request rate
Perl
Failed to load latest commit information.
bin Fix PodWeaver entries for cerbrus.pl
example Release version 0.01
lib/App Update example user agent info to include is_tablet
.gitignore Release version 0.01
Changes
README
README.pod Added README.pod
dist.ini Add is_tablet to App::Cerberus::Plugin::BrowserDetect response

README.pod

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:

Something went wrong with that request. Please try again.