From: Christopher Faulet <cfaulet@haproxy.com>
Date: Tue, 27 May 2025 16:48:21 +0000 (+0200)
Subject: DOC: hlua: Add a note to warn user about httpclient object reuse
X-Git-Tag: v3.2.0~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cb7a2444d149de8e0ce89d7b4a450e5c36822412;p=thirdparty%2Fhaproxy.git

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.
---

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index e8d494b02..250227de3 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -893,7 +893,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.
 
@@ -2581,7 +2583,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)