Updated docs

Author: javiereguiluz

rate_limiter.rst

@@ -7,19 +7,43 @@ Rate Limiter
     :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:
+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.
+
+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.
+
+Rate Limiting Strategies
+------------------------
+
+Symfony's rate limiter implements two of the most common strategies to enforce
+rate limits: **fixed window** and **token bucket**.
+
+Fixed Window Rate Limiter
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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 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
 ------------
 
@@ -33,39 +57,32 @@ install the associated Symfony Component in your application:
 Configuration
 -------------
 
-Use the following options to configure the behavior of the rate limiter:
+The following example creates two different rate limiters for an API service, to
+enforce different levels of service (free or paid):
 
 .. 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:
+            anonymous_api_limiter:
+                strategy: fixed_window
+                limit: 100
+                interval: 60m
+            authenticated_api_limiter:
+                strategy: token_bucket
+                limit: 5000
+                rate: { interval: 1h, amount: 5000 }
+
+In the ``anonymous_api_limiter``, when you make 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
+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
+number from being higher than 5,000).
 
 Rate Limiting in Action
 -----------------------
@@ -84,11 +101,12 @@ the number of requests to the API::
 
     class ApiController extends AbstractController
     {
-        public function index(LimiterInterface $limiter)
+        // the variable name must be the exact same as the rate limiter name
+        public function index(LimiterInterface $anonymous_api_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)) {
+            if (false === $anonymous_api_limiter->consume(1)) {
                 throw new TooManyRequestsHttpException();
             }
 
@@ -113,53 +131,34 @@ token is available. In those cases, use the ``reserve()`` and ``wait()`` methods
 
     class ApiController extends AbstractController
     {
-        public function registerUser(LimiterInterface $limiter)
+        public function registerUser(LimiterInterface $authenticated_api_limiter)
         {
             // this blocks the application until the given number of tokens can be consumed
-            $limiter->reserve(1)->wait();
+            $authenticated_api_limiter->reserve(1)->wait();
 
             // ...
         }
 
         // ...
     }
 
-Creating Multiple Rate Limiters
--------------------------------
+Rate Limiter Storage and Locking
+--------------------------------
 
-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:
+Rate limiters use the default cache and locking mechanisms defined in your
+Symfony application. If you prefer to change that, use the ``lock`` and
+``storage`` options:
 
 .. 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)
-        {
-            // ...
-        }
-    }
+            anonymous_api_limiter:
+                # ...
+                # the value is the name of any cache pool defined in your application
+                storage: 'app.redis_cache'
+                # 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