DOC: lua: Be explicit with the Reply object limits

In HTTP, when a lua action is evaluated, a reply object can be used to send
a response to the client and interrupt the transaction. This reply object is
converted into HTX and is limited to the response channel buffer. Its size,
once converted, cannot exceed the buffer size. There is no streaming at this
stage. However, this limitation was not documented.

Note that, for now, there is no easy way to know if the reply will fit or
not int the response channel buffer. Thus the reply must be reasonably
small. Otherwise a 500-Internal-Error message is returned.

This patch is related to the issue #1447. It may be backported as far as
2.2.

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 991dc6f..cd7fbbc 100644 (file)
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -2083,10 +2083,13 @@ TXN class
   processing after some data have been returned to the client (eg: a redirect).
   To do so, a reply may be provided. This object is optional and may contain a
   status code, a reason, a header list and a body. All these fields are
-  optional. When not provided, the default values are used. By default, with
-  an empty reply object, an empty HTTP 200 response is returned to the
-  client. If no reply object is provided, the transaction is terminated without
-  any reply.
+  optional. When not provided, the default values are used. By default, with an
+  empty reply object, an empty HTTP 200 response is returned to the client. If
+  no reply object is provided, the transaction is terminated without any
+  reply. If a reply object is provided, it must not exceed the buffer size once
+  converted into the internal HTTP representing. Because for now there is no
+  easy way to be sure it fits, it is probably better to keep it reasonably
+  small.
 
   The reply object may be fully created in lua or the class Reply may be used to
   create it.
@@ -2178,7 +2181,12 @@ Reply class
   **context**: action
 
   This class represents an HTTP response message. It provides some methods to
-  enrich it.
+  enrich it. Once converted into the internal HTTP representation, the response
+  message must not exceed the buffer size. Because for now there is no
+  easy way to be sure it fits, it is probably better to keep it reasonably
+  small.
+
+  See tune.bufsize in the configuration manual for dettails.
 
 .. code-block:: lua