[RateLimiter] Document the RateLimit object

javiereguiluz · javiereguiluz · commit 110191008400 · 2020-10-22T11:23:38.000+02:00
diff --git a/rate_limiter.rst b/rate_limiter.rst
@@ -212,6 +212,47 @@ processes by reserving unused tokens.
             $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.)
+
+That's why the ``consume()`` object returns a :class:`Symfony\\Component\\RateLimiter\\RateLimit`
+object which you can use to get the value of those HTTP headers::
+
+    // src/Controller/ApiController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
+    use Symfony\Component\RateLimiter\RateLimiter;
+
+    class ApiController extends AbstractController
+    {
+        public function index(RateLimiter $anonymousApiLimiter)
+        {
+            $limiter = $anonymousApiLimiter->create($request->getClientIp());
+            $limit = $limiter->consume();
+            if (false === $limit->isAccepted()) {
+                throw new TooManyRequestsHttpException();
+            }
+
+            // ...
+
+            $reponse = new Response($responseContents);
+            $response->headers->add([
+                'X-RateLimit-Remaining' => $limit->getRemainingTokens(),
+                'X-RateLimit-Reset' => $limit->getRetryAfter()->getTimestamp(),
+                'X-RateLimit-Limit' => $limit->getLimit(),
+            ]);
+
+            return $response;
+        }
+    }
+
 Rate Limiter Storage and Locking
 --------------------------------
 
