[HttpClient] Add documentation for Retryable client

http_client.rst

@@ -143,6 +143,7 @@ Some options are described in this guide:
 * `Query String Parameters`_
 * `Headers`_
 * `Redirects`_
+* `Retry Failed Requests`_
 * `HTTP Proxies`_
 
 Check out the full :ref:`http_client config reference <reference-http-client>`
@@ -654,6 +655,28 @@ making a request. Use the ``max_redirects`` setting to configure this behavior
         'max_redirects' => 0,
     ]);
 
+Retry Failed Requests
+~~~~~~~~~~~~~~~~~~~~~
+
+Some times, requests failed because of temporary issue in the server or
+because network issue. You can use the
+:class:`Symfony\\Component\\HttpClient\\RetryableHttpClient`
+client to automatically retry the request when it fails.::
+
+    use Symfony\Component\HttpClient\RetryableHttpClient;
+
+    $client = new RetryableHttpClient(HttpClient::create());
+
+The ``RetryableHttpClient`` uses a
+:class:`Symfony\\Component\\HttpClient\\Retry\\RetryDeciderInterface` to
+decide if the request should be retried, and a
+:class:`Symfony\\Component\\HttpClient\\Retry\\RetryBackOffInterface` to
+define the waiting time between each retry.
+
+By default, it retries until 3 attemps, the requests responding with a
+status code in (423, 425, 429, 500, 502, 503, 504, 507 or 510) and wait
+expentially from 1 second for the first retry, to 4 seconds at the 3rd attempt.
+
 HTTP Proxies
 ~~~~~~~~~~~~
 

reference/configuration/framework.rst

@@ -137,11 +137,34 @@ Configuration
     * `proxy`_
     * `query`_
     * `resolve`_
+
+    * :ref:`retry_failed <reference-http-client-retry-failed>`
+
+      * `backoff_service`_
+      * `decider_service`_
+      * :ref:`enabled <reference-http-client-retry-enabled>`
+      * `delay`_
+      * `http_codes`_
+      * `max_delay`_
+      * `max_retries`_
+      * `multiplier`_
+
     * `timeout`_
     * `max_duration`_
     * `verify_host`_
     * `verify_peer`_
 
+  * :ref:`retry_failed <reference-http-client-retry-failed>`
+
+    * `backoff_service`_
+    * `decider_service`_
+    * :ref:`enabled <reference-http-client-retry-enabled>`
+    * `delay`_
+    * `http_codes`_
+    * `max_delay`_
+    * `max_retries`_
+    * `multiplier`_
+
 * `http_method_override`_
 * `ide`_
 * :ref:`lock <reference-lock>`
@@ -742,6 +765,33 @@ If you use for example
 as the type and name of an argument, autowiring will inject the ``my_api.client``
 service into your autowired classes.
 
+.. _reference-http-client-retry-failed:
+
+By enabling the optional ``retry_failed`` configuration, the HTTP client service
+will automaticaly retry failed HTTP requests.
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        # ...
+        http_client:
+            # ...
+            retry_failed:
+                # backoff_service: app.custom_backoff
+                # decider_service:  app.custom_decider
+                http_codes: [429, 500]
+                max_retries: 2
+                delay: 1000
+                multiplier: 3
+                max_delay: 500
+
+            scoped_clients:
+                my_api.client:
+                    # ...
+                    retry_failed:
+                        max_retries: 4
+
 auth_basic
 ..........
 
@@ -769,6 +819,19 @@ in the `Microsoft NTLM authentication protocol`_. The value of this option must
 follow the format ``username:password``. This authentication mechanism requires
 using the cURL-based transport.
 
+backoff_service
+...............
+
+**type**: ``string``
+
+The service id used to compute the time to wait between retries. By default, it
+uses an instance of
+:class:`Symfony\\Component\\HttpClient\\Retry\\ExponentialBackOff` configured
+with ``delay``, ``max_delay`` and ``multiplier`` options. This class has to
+implement :class:`Symfony\\Component\\HttpClient\\Retry\\RetryBackOffInterface`.
+This options cannot be used along `delay`_, `max_delay`_ or `multiplier`_
+options.
+
 base_uri
 ........
 
@@ -837,6 +900,36 @@ ciphers
 A list of the names of the ciphers allowed for the SSL/TLS connections. They
 can be separated by colons, commas or spaces (e.g. ``'RC4-SHA:TLS13-AES-128-GCM-SHA256'``).
 
+decider_service
+...............
+
+**type**: ``string``
+
+The service id used to decide if a request should be retried. By default, it
+uses an instance of
+:class:`Symfony\\Component\\HttpClient\\Retry\\HttpStatusCodeDecider` configured
+with ``http_codes`` options. This class has to
+implement :class:`Symfony\\Component\\HttpClient\\Retry\\RetryDeciderInterface`.
+This options cannot be used along `http_codes`_ option.
+
+delay
+.....
+
+**type**: ``integer`` **default**: ``1000``
+
+The initial delay in milliseconds used to compute the waiting time between
+retries. This options cannot be used along `backoff_service`_ option.
+
+.. _reference-http-client-retry-enabled:
+
+enabled
+.......
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether to enable the support for retry failed HTTP request or not.
+This setting is automatically set to true when one of the child settings is configured.
+
 headers
 .......
 
@@ -845,6 +938,14 @@ headers
 An associative array of the HTTP headers added before making the request. This
 value must use the format ``['header-name' => header-value, ...]``.
 
+http_codes
+..........
+
+**type**: ``array`` **default**: ``[423, 425, 429, 500, 502, 503, 504, 507, 510]``
+
+The list of HTTP status codes that triggers a retry of the request.
+This options cannot be used along `decider_service`_ option.
+
 http_version
 ............
 
@@ -870,6 +971,15 @@ local_pk
 The path of a file that contains the `PEM formatted`_ private key of the
 certificate defined in the ``local_cert`` option.
 
+max_delay
+.........
+
+**type**: ``integer`` **default**: ``0``
+
+The maximum amount of milliseconds initial to wait between retries.
+Use ``0`` to not limit the duration.
+This options cannot be used along `backoff_service`_ option.
+
 max_duration
 ............
 
@@ -896,6 +1006,22 @@ max_redirects
 The maximum number of redirects to follow. Use ``0`` to not follow any
 redirection.
 
+max_retries
+...........
+
+**type**: ``integer`` **default**: ``3``
+
+The maximum number of retries before aborting. When the maximum is reach, the
+client returns the last received responses.
+
+multiplier
+..........
+
+**type**: ``float`` **default**: ``2``
+
+Multiplier to apply to the delay each time a retry occurs.
+This options cannot be used along `backoff_service`_ option.
+
 no_proxy
 ........