view release on metacpan or  search on metacpan

lib/App/Cerberus.pm  view on Meta::CPAN

1;

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

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 0.11

=head1 DESCRIPTION

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

=over

=item *

Geo-location

=item *

Time zone

=item *

User-agent info

=item *

Are they a spider?

=item *

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

=back

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 L<Plack>), freeing up your web processes to deal with just your own
code.

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

=head1 PLUGINS

=head2 L<App::Cerberus::Plugin::GeoIP>

Uses L<Geo::IP> with the L<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"
    }

=head2 L<App::Cerberus::Plugin::TimeZone>

Uses L<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 L<GeoIP|App::Cerberus::Plugin::GeoIP> plugin must be run before the
L<TimeZone|App::Cerberus::Plugin::TimeZone> plugin.

=head2 L<App::Cerberus::Plugin::BrowserDetect>

Uses L<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"