minor #18962 [RateLimiter] Add SlidingWindowLimiter::reserve() (alexandre-daubois)

This PR was merged into the 6.4 branch.

Discussion
----------

[RateLimiter] Add `SlidingWindowLimiter::reserve()`

Fix #18956

Doctor-RST's complaining but I'm not 100% sure how to adapt in this case, as it is a mix of deprecation and versionadded 🤔

Commits
-------

b5b0093 [RateLimiter] Add `SlidingWindowLimiter::reserve()`

Author: javiereguiluz

rate_limiter.rst

@@ -320,6 +320,11 @@ processes by reserving unused tokens.
             $limit->wait();
         } while (!$limit->isAccepted());
 
+.. versionadded:: 6.4
+
+    The support for the ``reserve()`` method for the ``SlidingWindow`` strategy
+    was introduced in Symfony 6.4.
+
 Exposing the Rate Limiter Status
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -348,7 +353,7 @@ the :class:`Symfony\\Component\\RateLimiter\\Reservation` object returned by the
             $limit = $limiter->consume();
             $headers = [
                 'X-RateLimit-Remaining' => $limit->getRemainingTokens(),
-                'X-RateLimit-Retry-After' => $limit->getRetryAfter()->getTimestamp(),
+                'X-RateLimit-Retry-After' => $limit->calculateTimeForTokens(1, 1),
                 'X-RateLimit-Limit' => $limit->getLimit(),
             ];
 
@@ -365,6 +370,19 @@ the :class:`Symfony\\Component\\RateLimiter\\Reservation` object returned by the
         }
     }
 
+.. versionadded:: 6.4
+
+    The :method:`Symfony\\Component\\RateLimiter\\Policy\\SlidingWindow::calculateTimeForTokens`
+    method was introduced in Symfony 6.4.
+
+.. deprecated:: 6.4
+
+    The :method:`Symfony\\Component\\RateLimiter\\Policy\\SlidingWindow::getRetryAfter`
+    method is deprecated since Symfony 6.4. Prior to this version, the
+    ``getRetryAfter()`` method must be used instead of the
+    :method:`Symfony\\Component\\RateLimiter\\Policy\\SlidingWindow::calculateTimeForTokens`
+    method.
+
 .. _rate-limiter-storage:
 
 Storing Rate Limiter State