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 <
[email protected]>
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.
