Rate Limiter

Fixed Window Rate Limiter

This is the simplest technique and it's based on setting a limit for a given interval of time (e.g. 5,000 requests per hour or 3 login attempts every 15 minutes).

In the diagram below, the limit is set to "5 tokens per hour". Each window starts at the first hit (i.e. 10:15, 11:30 and 12:30). As soon as there are 5 hits (the blue squares) in a window, all others will be rejected (red squares).

Its main drawback is that resource usage is not evenly distributed in time and it can overload the server at the window edges. In this example, there were 6 accepted requests between 11:00 and 12:00.

This is more significant with bigger limits. For instance, with 5,000 requests per hour, a user could make 4,999 requests in the last minute of some hour and another 5,000 requests during the first minute of the next hour, making 9,999 requests in total in two minutes and possibly overloading the server. These periods of excessive usage are called "bursts".

Sliding Window Rate Limiter

The sliding window algorithm is an alternative to the fixed window algorithm designed to reduce bursts. This is the same example as above, but then using a 1 hour window that slides over the timeline:

As you can see, this removes the edges of the window and would prevent the 6th request at 11:45.

To achieve this, the rate limit is approximated based on the current window and the previous window.

For example: the limit is 5,000 requests per hour; a user made 4,000 requests the previous hour and 500 requests this hour. 15 minutes into the current hour (25% of the window) the hit count would be calculated as: 75% * 4,000 + 500 = 3,500. At this point in time the user can only do 1,500 more requests.

The math shows that the closer the last window is, the more the hit count of the last window will affect the current limit. This will make sure that a user can do 5,000 requests per hour but only if they are evenly spread out.

Token Bucket Rate Limiter

This technique implements the token bucket algorithm, which defines continuously updating the budget of resource usage. It roughly works like this:

1. A bucket is created with an initial set of tokens;
2. A new token is added to the bucket with a predefined frequency (e.g. every second);
3. Allowing an event consumes one or more tokens;
4. If the bucket still contains tokens, the event is allowed; otherwise, it's denied;
5. If the bucket is at full capacity, new tokens are discarded.

The below diagram shows a token bucket of size 4 that is filled with a rate of 1 token per 15 minutes:

This algorithm handles more complex back-off burst management. For instance, it can allow a user to try a password 5 times and then only allow 1 every 15 minutes (unless the user waits 75 minutes and they will be allowed 5 tries again).

Rate Limiting a Controller

The simplest way to apply rate limiting to a controller is to add the RateLimit attribute. It references a limiter defined in the framework.rate_limiter configuration and, when the limit is exceeded, throws a TooManyRequestsHttpException, which Symfony turns into a 429 Too Many Requests response with a Retry-After header:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\ExpressionLanguage\Expression;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\RateLimit;
use Symfony\Component\Routing\Attribute\Route;

class ApiController extends AbstractController
{
    // if you don't define a 'key' argument, the key of the rate limiter
    // bucket uses the client IP, HTTP method and path
    #[RateLimit('api')]
    public function index(): JsonResponse
    {
        // ...
    }

    // restrict the limit to specific HTTP methods
    // (e.g. only rate-limit write operations; reads are unrestricted)
    #[RateLimit('api', methods: ['POST', 'PUT', 'PATCH', 'DELETE'])]
    public function edit(): JsonResponse
    {
        // ...
    }

    // build the bucket key from a submitted form field
    // (e.g. group requests by the submitted email so password-reset attempts
    // can't be spread across multiple IPs to bypass the limit)
    #[RateLimit('per_account', key: new Expression('request.request.get("email")'))]
    public function resetPassword(): Response
    {
        // ...
    }

    // build the bucket key from a route parameter; Symfony replaces the
    // {id} placeholder with the value of the 'id' route parameter
    #[Route('/user/{id}/messages', methods: ['POST'])]
    #[RateLimit('per_account', key: 'user-{id}')]
    public function sendMessage(): Response
    {
        // ...
    }

    // the 'key' argument also accepts a closure; it receives the controller
    // arguments, the current Request and the controller instance (in that order)
    #[RateLimit(
        'per_account',
        key: static function (array $args, Request $request): string {
            return $request->query->getString('email');
        },
    )]
    public function resetPasswordViaLink(): Response
    {
        // ...
    }

    // key the limit on the authenticated user instead of the client IP
    #[RateLimit('per_account', key: new Expression(
        'current_user().getUserIdentifier()'
    ))]
    public function profile(): Response
    {
        // ...
    }

    // specify the number of tokens consumed per request (defaults to 1)
    // (e.g. to take into account more expensive operations)
    #[RateLimit('api', tokens: 5)]
    public function export(): JsonResponse
    {
        // ...
    }
}

When the key is a string, Symfony replaces each {name} placeholder in it with the value of the request attribute of the same name (e.g. a route parameter). That attribute must exist and its value must be a string, an integer or a Stringable object.

When SecurityBundle is installed, the key expression can call any of the security functions, such as current_user() in the previous example.

You can stack several #[RateLimit] attributes on the same controller. Each limit is evaluated independently and all of them must pass for the request to be accepted. This is convenient to combine a broad per-IP quota with a stricter per-action limit:

1
2
3
4
5
6

#[RateLimit('global')]                    // applies to all methods
#[RateLimit('login', methods: ['POST'])]  // additional limit on POST /login
public function login(): Response
{
    // ...
}

Symfony checks the #[RateLimit] attributes before resolving the controller arguments, so rejected requests don't run any argument value resolver (e.g. one that queries the database to get an entity). Symfony also checks them before other attributes such as #[IsGranted], even if you write those attributes above #[RateLimit]. For example, when #[IsGranted] denies access to a user without the required role, that request still counts toward the rate limit.

The exception are limits whose key or condition is a closure or an expression that uses the args variable, because they need the controller arguments. Symfony checks those limits after resolving the arguments, in the same order as the attributes. For example, when #[IsGranted] is above #[RateLimit], the requests that it denies don't count toward the rate limit. If a key or condition only needs a route parameter, read it from the request (e.g. with a {id} placeholder or request.attributes.get('id')) instead of reading the related entity from args, so Symfony can check the limit before resolving the arguments.

For full control over the limiter logic, inject the rate limiter as a service in your controllers and services.

Applying a Rate Limit Conditionally

Sometimes a limit must only apply to some requests, such as the ones made by anonymous users. The methods argument only filters requests by HTTP method, so use the if argument for any other condition. For example, use the anonymous_api and authenticated_api limiters configured earlier to give authenticated users a larger quota than anonymous users:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\ExpressionLanguage\Expression;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\RateLimit;

class ApiController extends AbstractController
{
    // requests that match none of the conditions aren't rate limited,
    // so these two attributes use opposite conditions to cover all requests

    // applies only to anonymous users
    #[RateLimit('anonymous_api', if: new Expression('!is_authenticated()'))]
    // applies only to authenticated users, with a separate quota per user
    // (Symfony only evaluates the key when the condition is true, so
    // current_user() always returns a user here)
    #[RateLimit(
        'authenticated_api',
        key: new Expression('current_user().getUserIdentifier()'),
        if: new Expression('is_authenticated()'),
    )]
    public function index(): JsonResponse
    {
        // ...
    }
}

Like key, the if argument accepts an expression or a closure (with the same variables and arguments), but it must return a boolean. When it returns false, Symfony skips that limiter and the request doesn't consume any of its tokens.

Exposing the Rate Limit in the Response Headers

API clients usually need to know how much of their quota is left. Set the exposeHeaders option of the attribute to true to add the X-RateLimit-* headers to the responses of the rate-limited controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\RateLimit;

class ApiController extends AbstractController
{
    #[RateLimit('api', exposeHeaders: true)]
    public function index(): JsonResponse
    {
        // ...
    }
}

Both the successful responses and the 429 Too Many Requests responses then include the following headers:

X-RateLimit-Limit

The number of requests allowed by the limiter. When the attribute defines the tokens option, this is the limit of the rate limiter divided by the number of tokens consumed per request (rounded down).

X-RateLimit-Remaining

The number of requests left before the limiter rejects them.

X-RateLimit-Reset

The Unix timestamp when the limiter is back to its full capacity.

These values are specific to each client, so Symfony also marks the response as private to prevent shared HTTP caches from storing it. Symfony doesn't add any of these headers when the response already contains one of them, or when the limiter never gets back to its full capacity (e.g. when using the no_limiter policy).

When several #[RateLimit] attributes apply to the same request, the headers describe the exposed limiter with the fewest requests left. However, if a limiter rejects the request, the headers always describe that limiter, and if that limiter doesn't expose them, the response includes no X-RateLimit-* headers at all. This lets you combine a public limit with a hidden one:

1
2
3
4
5
6

#[RateLimit('api', exposeHeaders: true)] // clients see the state of this one
#[RateLimit('api_abuse')]                // clients never see this one
public function index(): JsonResponse
{
    // ...
}

Reading the Consumed Rate Limit

Sometimes you need the state of the rate limit inside the controller, for example to tell users how many more messages they can send. Type-hint a controller argument with the RateLimit class to get the rate limit consumed by the #[RateLimit] attributes of the controller. Symfony doesn't consume any extra tokens to inject it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Controller/ContactController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\RateLimit as RateLimitAttribute;
use Symfony\Component\RateLimiter\RateLimit;

class ContactController extends AbstractController
{
    #[RateLimitAttribute('contact_form')]
    public function send(RateLimit $rateLimit): Response
    {
        // ... send the message

        $this->addFlash('success', sprintf(
            'Message sent. You can send %d more messages.',
            $rateLimit->getRemainingTokens()
        ));

        return $this->redirectToRoute('contact');
    }
}

When several #[RateLimit] attributes apply to the same request, the argument gets the rate limit with the fewest requests left, regardless of the exposeHeaders option.

When no attribute applies to the request (because the controller doesn't define any or because their methods or if arguments exclude the request), the argument gets its default value or null if it's nullable. Otherwise, Symfony throws an exception.

Reacting to Exceeded Rate Limits

Whenever the #[RateLimit] attribute rejects a request, it dispatches a RateLimitExceededEvent object right before throwing the TooManyRequestsHttpException. Listen to it to log the rejection, report a metric or send an alert:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/EventListener/RateLimitExceededListener.php
namespace App\EventListener;

use Psr\Log\LoggerInterface;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\RateLimiter\Event\RateLimitExceededEvent;

#[AsEventListener]
class RateLimitExceededListener
{
    public function __construct(
        private LoggerInterface $logger,
    ) {
    }

    public function __invoke(RateLimitExceededEvent $event): void
    {
        $this->logger->warning('Rate limit "{limiter}" exceeded for key "{key}".', [
            'limiter' => $event->getLimiterName(),
            'key' => $event->getKey(),
        ]);
    }
}

Login throttling also dispatches this event when it rejects a login attempt. In that case, getLimiterName() returns the ID of the rate limiter service used by the firewall (security.login_throttling.<firewall name>.limiter by default, or the value of the limiter option if you define your own) and getKey() returns null. That's because the default login rate limiter combines two limits (one per IP address and another one per username and IP address), so no single key identifies the rejected attempt.

Injecting the Rate Limiter Service

After having configured one or more rate limiters, use the #[Target] attribute to inject a specific rate limiter in any service or controller. Symfony creates a target with the same name as the rate limiter.

For example, to inject the anonymous_api limiter defined earlier:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;

class ApiController extends AbstractController
{
    public function index(
        #[Target('anonymous_api')] RateLimiterFactoryInterface $rateLimiter
    ): Response
    {
        // ...
    }
}

Using the Rate Limiter Service

After having injected the rate limiter in any service or controller, call the consume() method to try to consume a given number of tokens. For example, this controller uses the previous rate limiter to control the number of requests to the API:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;

class ApiController extends AbstractController
{
    public function index(
        Request $request,
        #[Target('anonymous_api')] RateLimiterFactoryInterface $rateLimiter,
    ): Response
    {
        // create a limiter based on a unique identifier of the client
        // (e.g. the client's IP address, a username/email, an API key, etc.)
        $limiter = $rateLimiter->create($request->getClientIp());

        // the argument of consume() is the number of tokens to consume
        // and returns an object of type Limit
        if (false === $limiter->consume(1)->isAccepted()) {
            throw new TooManyRequestsHttpException();
        }

        // you can also use the ensureAccepted() method - which throws a
        // RateLimitExceededException if the limit has been reached
        // $limiter->consume(1)->ensureAccepted();

        // to reset the counter
        // $limiter->reset();

        // ...
    }
}

Wait until a Token is Available

Instead of dropping a request or process when the limit has been reached, you might want to wait until a new token is available. This can be achieved using the reserve() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;

class ApiController extends AbstractController
{
    public function registerUser(
        Request $request,
        #[Target('authenticated_api')] RateLimiterFactoryInterface $rateLimiter,
    ): Response
    {
        $apiKey = $request->headers->get('apikey');
        $limiter = $rateLimiter->create($apiKey);

        // this blocks the application until the given number of tokens can be consumed
        $limiter->reserve(1)->wait();

        // optional, pass a maximum wait time (in seconds), a MaxWaitDurationExceededException
        // is thrown if the process has to wait longer. E.g. to wait at most 20 seconds:
        //$limiter->reserve(1, 20)->wait();

        // ...
    }

    // ...
}

The reserve() method is able to reserve a token in the future. Only use this method if you're planning to wait, otherwise you will block other processes by reserving unused tokens.

1
2
3
4
5

// ...
do {
    $limit = $limiter->consume(1);
    $limit->wait();
} while (!$limit->isAccepted());

Exposing the Rate Limiter Status

When using a rate limiter in APIs, it's common to include some standard HTTP headers in the response to expose the limit status (e.g. remaining tokens, when new tokens will be available, etc.). When using the #[RateLimit] attribute, Symfony can add these headers for you.

Otherwise, use the RateLimit object returned by the consume() method (also available via the getRateLimit() method of the Reservation object returned by the reserve() method) to get the value of those HTTP headers:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// src/Controller/ApiController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;

class ApiController extends AbstractController
{
    public function index(Request $request, RateLimiterFactoryInterface $anonymousApiLimiter): Response
    {
        $limiter = $anonymousApiLimiter->create($request->getClientIp());
        $limit = $limiter->consume();
        $headers = [
            'X-RateLimit-Remaining' => $limit->getRemainingTokens(),
            'X-RateLimit-Limit' => $limit->getLimit(),
        ];

        if (false === $limit->isAccepted()) {
            throw new TooManyRequestsHttpException(
                $limit->getRetryAfter()->getTimestamp() - time(),
                headers: $headers,
            );
        }

        // ...

        $response = new Response('...');
        $response->headers->add($headers);

        return $response;
    }
}

Resetting the Rate Limiters in Tests

The cache.rate_limiter pool isn't cleared between tests, so a test that exhausts a limiter would make the following tests start with that limiter already exhausted. That's why, when the framework.test option is enabled, Symfony clears this pool every time the kernel is shut down with KernelTestCase::ensureKernelShutdown(). This happens at the end of each test and when booting a new kernel, so all limiters start fresh in every test. The state is still kept across all the requests made with the same kernel.

If a test relies on the tokens consumed by a previous test (or before a kernel shutdown in the same test), update it to consume those tokens itself.

Limiters that use their own cache_pool or storage_service aren't reset, because that pool or storage can contain other data. If you need a fresh state for them, clear the cache pool (or reset your custom storage) yourself, for example at the start of your test:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// tests/Controller/ApiControllerTest.php
namespace App\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class ApiControllerTest extends WebTestCase
{
    public function testTooManyRequests(): void
    {
        $client = static::createClient();

        // the pool defined with the "cache_pool" option of your limiter
        static::getContainer()->get('cache.anonymous_rate_limiter')->clear();

        // ...
    }
}

Giving a Fixed Key to Some Sub-Limiters

All sub-limiters use the key passed to create(), so in the example above both of them count requests per client IP. To give a fixed key to some of them, define the sub-limiters as a map instead of a list. A sub-limiter with a fixed key counts the requests of all clients together:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# config/packages/rate_limiter.yaml
framework:
    rate_limiter:
        two_per_minute:
            policy: 'fixed_window'
            limit: 2
            interval: '1 minute'
        global_quota:
            policy: 'fixed_window'
            limit: 5000
            interval: '1 hour'
        contact_form:
            policy: 'compound'
            limiters:
                # no key: uses the key passed to create()
                two_per_minute: ~
                # fixed key: shared by all clients
                global_quota: { key: 'global' }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// config/packages/rate_limiter.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'framework' => [
        'rate_limiter' => [
            'two_per_minute' => [
                'policy' => 'fixed_window',
                'limit' => 2,
                'interval' => '1 minute',
            ],
            'global_quota' => [
                'policy' => 'fixed_window',
                'limit' => 5000,
                'interval' => '1 hour',
            ],
            'contact_form' => [
                'policy' => 'compound',
                'limiters' => [
                    // no key: uses the key passed to create()
                    'two_per_minute' => null,
                    // fixed key: shared by all clients
                    'global_quota' => ['key' => 'global'],
                ],
            ],
        ],
    ],
]);

The controller shown above doesn't change: two_per_minute still allows two submissions per minute to each client IP, while global_quota also limits the contact form to 5,000 submissions per hour in total.