beheh / flaps
Modular library for rate limiting requests in applications
Installs: 218 406
Dependents: 2
Suggesters: 0
Security: 0
Stars: 65
Watchers: 4
Forks: 11
Open Issues: 3
Requires
- php: >=5.3.0
Requires (Dev)
- doctrine/cache: ~1.4
- phpunit/phpunit: ~4.0
- predis/predis: ~1.0
Suggests
- doctrine/cache: Enables a wide variety of caching systems as storage
- predis/predis: Enable Redis as storage system
This package is auto-updated.
Last update: 2023-10-06 22:27:18 UTC
README
Flaps is a modular library for rate limiting requests in PHP applications.
The library supports custom storage backends, throttling strategies and violation handlers for flexible integration into any project.
Developed by @beheh and licensed under the ISC license.
Requirements
- PHP 5.4 or newer
- Persistent-ish storage (e.g. Redis, APC or anything supported by Doctrine\Cache)
- Composer
Basic usage
use Predis\Client; use BehEh\Flaps\Storage\PredisStorage; use BehEh\Flaps\Flaps; use BehEh\Flaps\Throttling\LeakyBucketStrategy; // setup with Redis as storage backend $storage = new PredisStorage(new Client()); $flaps = new Flaps($storage); // allow 3 requests per 5 seconds $flaps->login->pushThrottlingStrategy(new LeakyBucketStrategy(3, '5s')); //or $flaps->__get('login')->pushThrottlingStrategy(...) // limit by ip (default: send "HTTP/1.1 429 Too Many Requests" and die() on violation) $flaps->login->limit($_SERVER['REMOTE_ADDR']);
Why rate limit?
There are many benefits from rate limiting your web application. At any point in time your server(s) could be hit by a huge number of requests from one or many clients. These could be:
- Malicious clients trying to degrade your applications performance
- Malicious clients bruteforcing user credentials
- Bugged clients repeating requests over and over again
- Automated web crawlers enumerating usernames or email adresses
- Penetration frameworks testing for vulnerabilities
- Bots registering a large number of users
- Bots spamming links to malicious sites
Most of these problems can be solved in a variety of ways, for example by using a spam filter or a fully configured firewall. Rate limiting is nevertheless a basic tool for improving application security, but offers no full protection.
Advanced examples
Application-handled violation
use BehEh\Flaps\Throttling\LeakyBucketStrategy; use BehEh\Flaps\Violation\PassiveViolationHandler; $flap = $flaps->__get('api'); $flap->pushThrottlingStrategy(new LeakyBucketStrategy(15, '10s')); $flap->setViolationHandler(new PassiveViolationHandler); if (!$flap->limit(filter_var(INPUT_GET, 'api_key'))) { die(json_encode(array('error' => 'too many requests'))); }
Multiple throttling strategies
use BehEh\Flaps\Throttling\LeakyBucketStrategy; $flap = $flaps->__get('add_comment'); $flap->pushThrottlingStrategy(new LeakyBucketStrategy(1, '30s')); $flap->pushThrottlingStrategy(new LeakyBucketStrategy(10, '10m')); $flap->limit($userid);
Storage
Redis
The easiest storage system to get started is Redis (via nrk/predis):
use Predis\Client; use BehEh\Flaps\Storage\PredisStorage; use BehEh\Flaps\Flaps; $storage = new PredisStorage(new Client('tcp://10.0.0.1:6379')); $flaps = new Flaps($storage);
Don't forget to composer require predis/predis
.
Doctrine cache
You can use any of the Doctrine cache implementations by using the DoctrineCacheAdapter:
use Doctrine\Common\Cache\ApcCache; use BehEh\Flaps\Storage\DoctrineCacheAdapter; use BehEh\Flaps\Flaps; $apc = new ApcCache(); $apc->setNamespace('MyApplication'); $storage = new DoctrineCacheAdapter($apc); $flaps = new Flaps($storage);
The Doctrine caching implementations can be installed with composer require doctrine/cache
.
Custom storage
Alternatively you can use your own storage system by implementing BehEh\Flaps\StorageInterface.
Throttling strategies
Leaky bucket strategy
This strategy is based on the leaky bucket algorithm. Each unique identifier of a flap corresponds to a leaky bucket. Clients can now access the buckets as much as they like, inserting water for every request. If a request would cause the bucket to overflow, it is denied. In order to allow later requests, the bucket leaks at a fixed rate.
use BehEh\Flaps\Throttle\LeakyBucketStrategy; $flap->pushThrottlingStrategy(new LeakyBucketStrategy(60, '10m'));
Custom throttling strategy
Once again, you can supply your own throttling strategy by implementing BehEh\Flaps\ThrottlingStrategyInterface.
Violation handler
You can handle violations either using one of the included handlers or by writing your own.
HTTP violation handler
The HTTP violation handler is the most basic violation handler, recommended for simple scripts. It simply sends the correct HTTP header (status code 429) and die()s. This is not recommended for any larger application and should be replaced by one of the more customizable handlers.
use BehEh\Flaps\Violation\HttpViolationHandler; $flap->setViolationHandler(new HttpViolationHandler); $flap->limit($identifier); // send "HTTP/1.1 429 Too Many Requests" and die() on violation
Passive violation handler
The passive violation handler allows you to easily react to violations.
limit()
will return false if the requests violates any throttling strategy, so you are able to log the request or return a custom error page.
use BehEh\Flaps\Violation\PassiveViolationHandler; $flap->setViolationHandler(new PassiveViolationHandler); if (!$flap->limit($identifier)) { // violation }
Exception violation handler
The exception violation handler can be used in larger frameworks. It will throw a ThrottlingViolationException whenever a ThrottlingStrategy is violated. You should be able to setup your exception handler to catch any ThrottlingViolationException.
use BehEh\Flaps\Violation\ExceptionViolationHandler; use BehEh\Flaps\Violation\ThrottlingViolationException; $flap->setViolationHandler(new ExceptionViolationHandler); try { $flap->limit($identifier); // throws ThrottlingViolationException on violation } catch (ThrottlingViolationException $e) { // violation }
Custom violation handler
The corresponding interface for custom violation handlers is BehEh\Flaps\ViolationHandlerInterface.
Default violation handler
The Flaps
object can pass a default violation handler to the flaps.
$flaps->setDefaultViolationHandler(new CustomViolationHandler); $flap = $flaps->__get('login'); $flap->addThrottlingStrategy(new TimeBasedThrottlingStrategy(1, '1s')); $flap->limit($identifier); // will use CustomViolationHandler