yiisoft / rate-limiter

RateLimiter helps to prevent abuse by limiting the number of requests that could be me made consequentially.

Yii Rate Limiter Middleware

Rate limiter middleware helps to prevent abuse by limiting the number of requests that could be me made consequentially.

For example, you may want to limit the API usage of each user to be at most 100 API calls within a period of 10 minutes. If too many requests are received from a user within the stated period of the time, a response with status code 429 (meaning "Too Many Requests") should be returned.

Requirements

• PHP 8.0 or higher.

Installation

The package could be installed with Composer:

composer require yiisoft/rate-limiter

General usage

use Psr\Http\Message\ServerRequestInterface;
use Yiisoft\Yii\RateLimiter\LimitRequestsMiddleware;
use Yiisoft\Yii\RateLimiter\Counter;
use Nyholm\Psr7\Factory\Psr17Factory;
use Yiisoft\Yii\RateLimiter\Policy\LimitAlways;
use Yiisoft\Yii\RateLimiter\Policy\LimitPerIp;
use Yiisoft\Yii\RateLimiter\Policy\LimitCallback;
use Yiisoft\Yii\RateLimiter\Storage\StorageInterface;
use Yiisoft\Yii\RateLimiter\Storage\SimpleCacheStorage;

/** @var StorageInterface $storage */
$storage = new SimpleCacheStorage($cache);

$counter = new Counter($storage, 2, 5);
$responseFactory = new Psr17Factory();

$middleware = new LimitRequestsMiddleware($counter, $responseFactory); // LimitPerIp by default

In the above 2 is the maximum number of counter increments (requests) that could be performed before increments are limited and 5 is a period to apply limit to, in seconds.

The Counter implements generic cell rate limit algorithm (GCRA) that ensures that after reaching the limit further increments are distributed equally.

Note: While it is sufficiently effective, it is preferred to use Nginx or another webserver capabilities for rate limiting. This package allows rate-limiting in the project with deployment environment you cannot control such as installable CMS.

Implementing your own limiting policy

There are two ready to use limiting policies available in the package:

• LimitAlways - to count all incoming requests.
• LimitPerIp - to count requests from different IPs separately.

These could be applied as follows:

$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitPerIp());
// or
$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitAlways());

Easiest way to customize a policy is to use LimitCallback:

$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitCallback(function (ServerRequestInterface $request): string {
    // return user id from database if authentication id used i.e. limit guests and each authenticated user separately.
}));

Another way it to implement Yiisoft\Yii\RateLimiter\Policy\LimitPolicyInterface and use it in a similar way as above.

Implementing your own counter storage

There are two ready to use counter storages available in the package:

• \Yiisoft\Yii\RateLimiter\Storage\SimpleCacheStorage - stores counters in any PSR-16 cache.
• \Yiisoft\Yii\RateLimiter\Storage\ApcuStorage - stores counters by using the APCu PHP extension while taking concurrency into account.

To use your own storage implement Yiisoft\Yii\RateLimiter\Storage\StorageInterface.

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii Rate Limiter Middleware is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates

rate-limiter's Issues

update irc link

What steps will reproduce the problem?

What is the expected result?

What do you get instead?

Additional info

Q	A
Version	1.0.?
PHP version
Operating system

Sometimes tests is fail

consequentially?

In description, did you mean 'number of subsequent requests', rather than 'consequently'?

But then I may be misreading the intentioned functionality.

Interesting to see this kind of functionality being clearly exposed for implementation.
Mike B

Refactoring idea: move counter ID to method argument

Since counter ID is required, it could be moved to method argument i.e.

interface RateLimiter
{
    public function hit(string $id): SomeStats;
}

Concurrent request issues

When concurrent requests are made, flow restriction cannot be applied.
for example,When using caching such as Apcu or Redis, it relies on "TheoreticalNextIncrementTime",It may be dirty reading.

Fix exception messages

The counter ID should be set. -> The counter ID must be set.

Since ID is required.

PSR ClockInterface instead of TimerInterface

Should we replace \Yiisoft\Yii\RateLimiter\Time\TimerInterface with the one from https://www.php-fig.org/psr/psr-20?

Fix BC checker

Use bc.yml from yiisoft/package-template

update src folder link

What steps will reproduce the problem?

http=>https

What is the expected result?

What do you get instead?

Additional info

Q	A
Version	1.0.?
PHP version
Operating system

update root folder link

What steps will reproduce the problem?

http=>https

What is the expected result?

What do you get instead?

Additional info

Q	A
Version	1.0.?
PHP version
Operating system

Describe setting ID

State in readme about the fact that by default limiter doesn't work by-user and show examples on how to choose ID correctly.