Add documention on http client pool

Author: joelwurtz

components/client-common.rst

@@ -81,3 +81,67 @@ PluginClient
 ------------
 
 See :doc:`/plugins/introduction`
+
+HttpClientPool
+--------------
+
+This kind of client allows to send a request on a pool of ``HttpClient`` and/or ``HttpAsyncClient`̀`.
+
+You can attach http clients to this kind of client by using the ``addHttpClient`` method::
+
+    use Http\Client\Common\HttpClientPool\LeastUsedClientPool;
+    use Http\Discovery\HttpAsyncClientDiscovery;
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Discovery\MessageFactoryDiscovery;
+
+    $messageFactory = MessageFactoryDiscovery::find();
+
+    $httpClient = HttpClientDiscovery::find();
+    $httpAsyncClient = HttpAsyncClientDiscovery::find();
+
+    $httpClientPool = new LeastUsedClientPool();
+    $httpClientPool->addHttpClient($httpClient);
+    $httpClientPool->addHttpClient($httpAsyncClient);
+
+    $httpClientPool->sendRequest($messageFactory->createRequest('GET', 'http://example.com/update'));
+
+Using this kind of client is useful is some use cases :
+
+- When using a cluster (like a elasticsearch service with multiple master nodes)
+- When you want to use fallback servers with the combination of the ``RetryPlugin`` (see :doc:`/plugins/retry`)
+
+Each added client will be decorated by the ``HttpClientPoolItem`` class unless it's already an instance of this class.
+It allows the pool to be aware of the number processing requests in real time, and also deactivate a client on a error,
+it will be reenable automatically after a certain amount of time. However this behavior is not enabled by default (it
+reenable after 0 second, so after each request), but you can enable this behavior, client by client by directly using
+the ``HttpClientPoolItem`` class::
+
+    // Reenable after 30 seconds
+    $httpClientPool->addHttpClient(new HttpClientPoolItem($httpClient, 30));
+    // Reenable after 3 minutes (180 seconds)
+    $httpClientPool->addHttpClient(new HttpClientPoolItem($httpAsyncClient, 180));
+
+This client cannot be used directly as it's only an abstraction. Each implementation as a specific strategy on how to
+choose a client into the pool :
+
+LeastUsedClientPool
+*******************
+
+``LeastUsedClientPool`` choose the client with less processing request in the pool. As it sounds the best strategy for
+sending a request on a pool of clients, the current implementation have some flaws :
+
+- The counter is not shared between php process, so this strategy is not so useful in a web context, however it will make
+  better sense in a php command line context.
+- The counter of a request is decremented after each client call, so using this with the ``sendRequest`` method is
+  useless, as the first client will always be at 0 after each call. It's better to use the async mechanism, with the
+  ``sendAsyncRequest`` method to correctly distribute requests across your pool.
+
+A disabled client will be remove for the pool until it is reenable, if none are available it will throw a
+``NotFoundHttpClientException`̀`
+
+RoundRobinClientPool
+********************
+
+``RoundRobinClientPool`` keeps an internal pointer on the pool. At each call the pointer is moved to the next client, if
+the current client is disabled it will move to the next client, and if none are available it will throw a
+``NotFoundHttpClientException`̀`