Fixes and improvements

Author: javiereguiluz

rate_limiter.rst

@@ -9,7 +9,8 @@ Rate Limiter
 A "rate limiter" controls how frequently some event (e.g. an HTTP request or a
 login attempt) is allowed to happen. Rate limiting is commonly used as a
 defensive measure to protect services from excessive use (intended or not) and
-maintain their availability.
+maintain their availability. It's also useful to control your internal or
+outbound processes (e.g. limit the number of simultaneously processed messages).
 
 Symfony uses these rate limiters in built-in features like "login throttling",
 which limits how many failed login attempts a user can make in a given period of
@@ -28,17 +29,19 @@ This is the simplest technique and it's based on setting a limit for a given
 interval of time. For example: 5,000 requests per hour or 3 login attempts
 every 15 minutes.
 
-Its main drawback is that resource usage is not evenly distributed in time. In
-the previous example, a user could make the 5,000 requests in the first minute
-(possibly overloading the server) and do nothing for the rest of the hour.
+Its main drawback is that resource usage is not evenly distributed in time and
+it can overload the server at the window edges. In the previous example, a user
+could make the 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.
 
 Token Bucket Rate Limiter
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This technique implements the `token bucket algorithm`_, which defines a
 continuously updating budget of resource usage. It roughly works like this:
 
-* A bucket is initially created with zero or more tokens;
+* A bucket is created with an initial set of tokens;
 * A new token is added to the bucket with a predefined frequency (e.g. every second);
 * Allowing an event consumes one or more tokens;
 * If the bucket still contains tokens, the event is allowed; otherwise, it's denied;
@@ -65,20 +68,26 @@ enforce different levels of service (free or paid):
     # config/packages/rate_limiter.yaml
     framework:
         rate_limiter:
-            anonymous_api_limiter:
+            anonymous_api:
                 strategy: fixed_window
                 limit: 100
-                interval: 60m
-            authenticated_api_limiter:
+                interval: '60 minutes'
+            authenticated_api:
                 strategy: token_bucket
                 limit: 5000
-                rate: { interval: 1h, amount: 5000 }
+                rate: { interval: '1 hour', amount: 5000 }
+
+.. note::
+
+    The value of the ``interval`` option must be a number followed by any of the
+    units accepted by the `PHP date relative formats`_ (e.g. ``3 seconds``,
+    ``10 hours``, ``1 day``, etc.)
 
-In the ``anonymous_api_limiter``, when you make the first HTTP request, you can
+In the ``anonymous_api`` limiter, after making the first HTTP request, you can
 make up to 100 requests in the next 60 minutes. After that time, the counter
 resets and you have another 100 requests for the following 60 minutes.
 
-In the ``authenticated_api_limiter``, when you make the first HTTP request you
+In the ``authenticated_api`` limiter, after making the first HTTP request you
 are allowed to make up to 5,000 HTTP requests in total, and this number grows
 at a rate of another 5,000 requests per hour. If you don't make that number of
 requests, the unused ones don't accumulate (the ``limit`` option prevents that
@@ -92,7 +101,7 @@ or controller and 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::
 
-    // src/Controller/LuckyController.php
+    // src/Controller/ApiController.php
     namespace App\Controller;
 
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
@@ -101,15 +110,23 @@ the number of requests to the API::
 
     class ApiController extends AbstractController
     {
-        // the variable name must be the exact same as the rate limiter name
-        public function index(LimiterInterface $anonymous_api_limiter)
+        // the variable name must be: "rate limiter name" + "limiter" suffix
+        public function index(LimiterInterface $anonymousApiLimiter)
         {
+            // 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 = $anonymousApiLimiter->create($request->getClientIp());
+
             // the argument of consume() is the number of tokens to consume
-            // and returns FALSE if they cannot be consumed
-            if (false === $anonymous_api_limiter->consume(1)) {
+            // and returns an object of type Limit
+            if (false === $anonymous_api_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();
+
             // ...
         }
 
@@ -131,10 +148,12 @@ token is available. In those cases, use the ``reserve()`` and ``wait()`` methods
 
     class ApiController extends AbstractController
     {
-        public function registerUser(LimiterInterface $authenticated_api_limiter)
+        public function registerUser(LimiterInterface $authenticatedApiLimiter)
         {
+            $limiter = $authenticatedApiLimiter->create($request->getClientIp());
+
             // this blocks the application until the given number of tokens can be consumed
-            $authenticated_api_limiter->reserve(1)->wait();
+            $limiter->consume(1)->wait();
 
             // ...
         }
@@ -158,7 +177,11 @@ Symfony application. If you prefer to change that, use the ``lock`` and
                 # ...
                 # the value is the name of any cache pool defined in your application
                 storage: 'app.redis_cache'
+                # or define a service implementing StorageInterface to use a different
+                # mechanism to store the limiter information
+                storage: 'App\RateLimiter\CustomRedisStorage'
                 # the value is the name of any lock defined in your application
                 lock: 'app.rate_limiter_lock'
 
 .. _`token bucket algorithm`: https://en.wikipedia.org/wiki/Token_bucket
+.. _`PHP date relative formats`: https://www.php.net/datetime.formats.relative