franzip/throttler

Simple rate limiter and usage tracker component.

, _(*1)

Throttler

A simple, general purpose, rate limiter and usage tracker library., _(*2)

Installing via Composer (recommended)

Install composer in your project:, _(*3)

curl -s http://getcomposer.org/installer | php

Create a composer.json file in your project root:, _(*4)

{
    "require": {
        "franzip/throttler": "1.0.*"
    }
}

Install via composer, _(*5)

php composer.phar install

Description

Once instantiated, the object must always be explicitly activated with the provided start() method., _(*6)

Basically, you set a timeframe (it can be 24 hours, 2 seconds, 30 minutes, etc.), a global limit and the things you want to keep track of, and you're ready to go., _(*7)

You can also set an additional limit that will applied as limit to each single component you are tracking., _(*8)

You can change the given parameters only after you stop the current instance from tracking with the provided stop() method., _(*9)

The Throttler will detect when a given timeframe is expired: all its internal states will be reset and a new timeframe will be computed., _(*10)

If your code need to access any Throttler attributes, just use the provided getters (getName, getGlobalThreshold, etc.). See the constructor., _(*11)

Constructor

$throttler = new Throttler($name, $globalThreshold, $metric, $metricFactor = 1,
                           $componentThreshold = null, $components = array());

Allowed $metric

• 'sec': Compute the timeframe in (seconds * $metricFactor)
• 'min': Compute the timeframe in (minutes * $metricFactor)
• 'hrs': Compute the timeframe in (hours * $metricFactor)

Basic Usage (default arguments)

Example 1: using Throttler to cap incoming requests. The total amount of requests will be capped to 30 per hour., _(*12)

use Franzip\Throttler\Throttler;

// Setting things up
// Max 30 total requests per hour
$throttler = new Throttler('requests', 30, 'hrs');

// Nothing happens and the call will return false since there is nothing to track
$throttler->start();

// Add remote addresses to track...
$throttler->addComponents('AddressToTrack1');
$throttler->addComponents('AddressToTrack2');
$throttler->addComponents('AddressToTrack3');
// Bulk adding
$throttler->addComponents(array('AddressToTrack4',
                                'AddressToTrack5',
                                'AddressToTrack6',
                                ...));
...

// Start tracking (timeframe starts now)
$throttler->start();

if ($throttler->updateComponent('AddressToTrack1')) {
    // handle update success
} else {
    // handle update failure
}

$numOfRequests = 31;

// will return false since the global limit is 30
$throttler->updateComponent('AddressToTrack1', $numOfRequests);

...

// Remove all stuff to track
$throttler->stop();
$throttler->setComponents(array());

Usage (custom arguments)

Example 2: using Throttler to cap incoming requests., _(*13)

The total amount of requests will be capped to 100 per day., _(*14)

The amount of incoming requests from each address will be capped to 10 per day., _(*15)

use Franzip\Throttler\Throttler;

// Setting things up
// Max 100 total requests per day
// Max 10 requests from each tracked address per day
$throttler = new Throttler('requests', 100, 'hrs', 24,
                           10, array('AddressToTrack1',
                                     'AddressToTrack2',
                                     ...));

// Start tracking (timeframe starts now)
$throttler->start();

if ($throttler->updateComponent('AddressToTrack1')) {
    // handle success
} else {
    // handle failure
}

isActive()

Return whether tracking is turned on., _(*16)

use Franzip\Throttler\Throttler;

$throttler = new Throttler('requests', 100, 'hrs');

// false
$throttler->isActive();

// false, there's nothing to track yet.
$throttler->start();

// false
$throttler->isActive();

$throttler->addComponents(array('foo', 'bar'));

// true, we have something to track
$throttler->start();

// true
$throttler->isActive();

// reset the instance (this will also stop tracking)
$throttler->reset();

// false
$throttler->isActive();

reset()

You can revert a Throttler object status to when it was instantiated. Just use the reset() method at anytime., _(*17)

use Franzip\Throttler\Throttler;

$throttler = new Throttler('requests', 100, 'hrs');
// Change time cap to 2 hours
$throttler->setMetricFactor(2);
// Change time cap to 2 minutes
$throttler->setMetric('min');
// Change global limit to 50
$throttler->setGlobalThreshold(50);

...

$throttler->reset();
// reverted to 100
$throttler->getGlobalThreshold();
// reverted to 'hrs'
$throttler->getMetric();

TODOs

• [x] A decent exceptions system.
• [x] Move validation to external class.
• [x] Allow bulk components adding.
• [ ] Refactoring messy tests.
• [ ] Refactoring update-checking methods.

License

MIT Public License., _(*18)