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.09 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": 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: 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 * CPAN Ratings * Search MetaCPAN AUTHOR Clinton Gormley 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.