[HttpClient] Add support for pausing responses

Author: alexandre-daubois

http_client.rst

@@ -1043,6 +1043,10 @@ following methods::
     // returns detailed logs about the requests and responses of the HTTP transaction
     $httpLogs = $response->getInfo('debug');
 
+    // the special "pause_handler" info item is a callable that allows to delay the request
+    // this helps implement delayed retries or throttling streams for example
+    $response->getInfo('pause_handler')(2);
+
 .. note::
 
     ``$response->toStream()`` is part of :class:`Symfony\\Component\\HttpClient\\Response\\StreamableInterface`.
@@ -1053,6 +1057,10 @@ following methods::
     about the response. Some of them might not be known yet (e.g. ``http_code``)
     when you'll call it.
 
+.. versionadded:: 5.2
+
+    The ``pause_handler`` info item was introduced in Symfony 5.2.
+
 .. _http-client-streaming-responses:
 
 Streaming Responses