xp-forge/ratelimit

v3.2.0 2024-03-24 13:13 UTC

This package is auto-updated.

Last update: 2024-12-24 14:49:16 UTC


README

Build status on GitHub XP Framework Module BSD Licence Requires PHP 7.0+ Supports PHP 8.0+ Latest Stable Version

A rate limiting can be used to limit the rate at which physical or logical resources are accessed, e.g. to protect them from intentional or unintentional overuse.

Restricting usage

Imagine you don't want to run more than two tasks per second:

use util\invoke\RateLimiting;

$rateLimiter= new RateLimiting(2);
foreach ($tasks as $task) {
  $rateLimiter->acquire();    // will wait if necessary
  $task->run();
}

Restricting bandwidth

You can implement bandwidth throttling by acquiring a permit for each byte:

use util\invoke\{RateLimiting, Rate, Per};

$rateLimiter= new RateLimiting(new Rate(1000000, Per::$MINUTE));
while ($bytes= $source->read()) {
  $rateLimiter->acquire(strlen($bytes));
  $target->write($bytes);
}

Rate-limiting users

Implement a filter like the following:

use web\{Filter, Error};
use util\invoke\{RateLimiting, Rate, Per};

class RateLimitingFilter implements Filter {
  private $rates, $rate, $timeout;

  public function __construct(KeyValueStorage $rates) {
    $this->rates= $rates;
    $this->rate= new Rate(5000, Per::$HOUR);
    $this->timeout= 0.2;
  }

  public function filter($request, $response, $invocation) {
    $remote= $request->header('Remote-Addr');

    $limits= $this->rates->get($remote) ?: new RateLimiting($this->rate);
    $permitted= $limits->tryAcquiring(1, $this->timeout);
    $this->rates->put($remote, $limits);

    $response->header('X-RateLimit-Limit', $limits->rate()->value());
    $response->header('X-RateLimit-Remaining', $limits->remaining());
    $response->header('X-RateLimit-Reset', $limits->resetTime());

    if (!$permitted) {
      throw new Error(429, 'Rate limit exceeded');
    }

    return $invocation->proceed($request, $response);
  }
}

Further reading