DOC: hlua: Add a note to warn user about httpclient object reuse

It is not supported to reuse an lua httpclient instance to process several
requests. A new object must be created for each request. Thanks to the
previous patch ("BUG/MEDIUM: httpclient: Throw an error if an lua httpclient
instance is reused"), an error is now reported if this happens. But it is
not obvious for users. So the lua-api docuementation was updated accordingly.

This patch is related to issue #2986. It should be backported with the
commit above.

(cherry picked from commit cb7a2444d149de8e0ce89d7b4a450e5c36822412)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit dc4d8da0ddc16e146d8df434c4388be71a70e4dd)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 30f9d7e..fc742c2 100644 (file)
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -859,7 +859,9 @@ Core class
 
   **context**: init, task, action
 
-  This function returns a new object of a *httpclient* class.
+  This function returns a new object of a *httpclient* class. An *httpclient*
+  object must be used to process one and only one request. It must never be
+  reused to process several requests.
 
   :returns: A :ref:`httpclient_class` object.
 
@@ -2523,7 +2525,9 @@ HTTPClient class
 .. js:class:: HTTPClient
 
    The httpclient class allows issue of outbound HTTP requests through a simple
-   API without the knowledge of HAProxy internals.
+   API without the knowledge of HAProxy internals. Any instance must be used to
+   process one and only one request. It must never be reused to process several
+   requests.
 
 .. js:function:: HTTPClient.get(httpclient, request)
 .. js:function:: HTTPClient.head(httpclient, request)