[RateLimiter] Added the docs for the new component

Author: javiereguiluz

index.rst

@@ -52,6 +52,7 @@ Topics
     notifier
     performance
     profiler
+    rate_limiter
     routing
     security
     session

rate_limiter.rst

@@ -0,0 +1,165 @@
+Rate Limiter
+============
+
+.. versionadded:: 5.2
+
+    The RateLimiter component was introduced in Symfony 5.2 as an
+    :doc:`experimental feature </contributing/code/experimental>`.
+
+A "rate limiter" controls how frequently some event (e.g. an HTTP request or a
+login attempt) is allowed to happen. It implements a `token bucket algorithm`_,
+which roughly works like this:
+
+* A bucket is initially created with zero or more 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;
+* If the bucket is at full capacity, new tokens are discarded.
+
+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
+time, but you can use them for your own features too.
+
+Installation
+------------
+
+Before using a rate limiter for the first time, run the following command to
+install the associated Symfony Component in your application:
+
+.. code-block:: terminal
+
+    $ composer require symfony/rate-limiter
+
+Configuration
+-------------
+
+Use the following options to configure the behavior of the rate limiter:
+
+.. code-block:: yaml
+
+    # config/packages/rate_limiter.yaml
+    framework:
+        rate_limiter:
+            limiters:
+                api_requests:
+                    # maximum number of tokens allowed in the bucket
+                    limit: 100
+                    # how many tokens are created and how often
+                    rate:
+                        amount: 100
+                        interval: '1 hour'
+
+This example creates a rate limiter to restrict the number of HTTP requests of
+some API to 100 per hour.
+
+There are other options that you can optionally define if needed:
+
+.. code-block:: yaml
+
+    # config/packages/rate_limiter.yaml
+    framework:
+        rate_limiter:
+            limiters:
+                api_requests:
+                    # ...
+                    lock:
+                    storage:
+                    strategy:
+                    interval:
+
+Rate Limiting in Action
+-----------------------
+
+After having installed and configured the rate limiter, inject it in any service
+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
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
+    use Symfony\Component\RateLimiter\LimiterInterface;
+
+    class ApiController extends AbstractController
+    {
+        public function index(LimiterInterface $limiter)
+        {
+            // the argument of consume() is the number of tokens to consume
+            // and returns FALSE if they cannot be consumed
+            if (false === $limiter->consume(1)) {
+                throw new TooManyRequestsHttpException();
+            }
+
+            // ...
+        }
+
+        // ...
+    }
+
+.. note::
+
+    In a real application, instead of checking the rate limiter in all the API
+    controller methods, create an :ref:`event listener or subscriber </event_dispatcher>`
+    for the :ref:`kernel.request event <component-http-kernel-kernel-request>`
+    and check the rate limiter once for all requests.
+
+In other scenarios you may want instead to wait as long as needed until a new
+token is available. In those cases, use the ``reserve()`` and ``wait()`` methods::
+
+    // src/Controller/LuckyController.php
+    // ...
+
+    class ApiController extends AbstractController
+    {
+        public function registerUser(LimiterInterface $limiter)
+        {
+            // this blocks the application until the given number of tokens can be consumed
+            $limiter->reserve(1)->wait();
+
+            // ...
+        }
+
+        // ...
+    }
+
+Creating Multiple Rate Limiters
+-------------------------------
+
+You can define any number of rate limiters in the application. For example, you
+could set different API request limits for anonymous and authenticated users:
+
+.. code-block:: yaml
+
+    # config/packages/rate_limiter.yaml
+    framework:
+        rate_limiter:
+            limiters:
+                # 1 request per minute for anonymous users
+                anonymous_api_requests:
+                    limit: 1
+                    rate:
+                        amount: 1
+                        interval: '1 minute'
+                # 85 requests per minute for authenticated users
+                authenticated_api_requests:
+                    limit: 85
+                    rate:
+                        amount: 85
+                        interval: '1 minute'
+
+Now you can inject each rate limiter using the same name as in the configuration::
+
+    // src/Controller/LuckyController.php
+    // ...
+
+    class ApiController extends AbstractController
+    {
+        public function index(LimiterInterface $authenticated_api_requests)
+        {
+            // ...
+        }
+    }
+
+.. _`token bucket algorithm`: https://en.wikipedia.org/wiki/Token_bucket