App::Cerberus - A pluggable Perl web service to preprocess web requests. Plugins can add geo, timezone and browser metadata, and throttle request rate.
version 0.10
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.
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" }
Uses Time::OlsonTZ::Data to provide the current timezone for the user, and it's offset from GMT.
"tz": { "short_name": "EDT", "name": "America/New_York", "dst": "1", "gmt_offset": "-14400" }
The GeoIP plugin must be run before the TimeZone plugin.
Uses HTTP::BrowserDetect to provide data about the user agent and recognises the most well known robots.
"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" }
Set per-second, per-minute, per-hour, per-day and per-month request limits. Different limits can be applied to different IP ranges.
"throttle": { "range": "google", "reason": "second", "sleep": 10, "request_count": 12 }
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.
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
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:
init()
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.
See cerberus.pl for more options.
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
Clinton Gormley <drtech@cpan.org>
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.
To install App::Cerberus, copy and paste the appropriate command in to your terminal.
cpanm
CPAN shell
perl -MCPAN -e shell install App::Cerberus
For more information on module installation, please visit the detailed CPAN module installation guide.