DOC: lua: fix lua API
This patch fix the Lua API documentation, and adds some internal link
between values returned and associated class.
This patch can be backported in 1.6.
diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 9972c49..cab8943 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -119,34 +119,50 @@
.. js:attribute:: core.emerg
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "emergency" (0).
.. js:attribute:: core.alert
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "alert" (1).
.. js:attribute:: core.crit
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "critical" (2).
.. js:attribute:: core.err
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "error" (3).
.. js:attribute:: core.warning
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "warning" (4).
.. js:attribute:: core.notice
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "notice" (5).
.. js:attribute:: core.info
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "info" (6).
.. js:attribute:: core.debug
+ :returns: integer
+
This attribute is an integer, it contains the value of the loglevel "debug" (7).
.. js:function:: core.log(loglevel, msg)
@@ -178,9 +194,9 @@
.. code-block:: lua
- function Debug(msg)
- core.log(core.debug, msg)
- end
+ function Debug(msg)
+ core.log(core.debug, msg)
+ end
..
.. js:function:: core.Info(msg)
@@ -192,9 +208,9 @@
.. code-block:: lua
- function Info(msg)
- core.log(core.info, msg)
- end
+ function Info(msg)
+ core.log(core.info, msg)
+ end
..
.. js:function:: core.Warning(msg)
@@ -206,9 +222,9 @@
.. code-block:: lua
- function Warning(msg)
- core.log(core.warning, msg)
- end
+ function Warning(msg)
+ core.log(core.warning, msg)
+ end
..
.. js:function:: core.Alert(msg)
@@ -220,9 +236,9 @@
.. code-block:: lua
- function Alert(msg)
- core.log(core.alert, msg)
- end
+ function Alert(msg)
+ core.log(core.alert, msg)
+ end
..
.. js:function:: core.add_acl(filename, key)
@@ -283,7 +299,7 @@
function(txn)
..
- * **txn** (*class TXN*): this is a TXN object used for manipulating the
+ * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
current request or TCP stream.
Here, an exemple of action registration. the action juste send an 'Hello world'
@@ -353,7 +369,7 @@
string function(txn, [p1 [, p2 [, ... [, p5]]]])
..
- * **txn** (*class txn*): this is the txn object associated with the current
+ * **txn** (:ref:`txn_class`): this is the txn object associated with the current
request.
* **p1** .. **p5** (*string*): this is a list of string arguments declared in
the haroxy configuration file. The number of arguments doesn't exceed 5.
@@ -398,8 +414,16 @@
function(applet)
..
+ * **applet** *applet* will be a :ref:`applettcp_class` or a
+ :ref:`applethttp_class`. It depends the type of registered applet. An applet
+ registered with the 'http' value for the *mode* parameter will gets a
+ :ref:`applethttp_class`. If the *mode* value is 'tcp', the applet will gets
+ a :ref:`applettcp_class`.
+
- * **txn** (*class AppletTCP*) or (*class AppletHTTP*): this is an object used
- for manipulating the current HTTP request or TCP stream.
+ **warning**: Applets of type 'http' cannot be called from 'tcp-*'
+ rulesets. Only the 'http-*' rulesets are authorized, this means
+ that is not possible to call an HTTP applet from a proxy in tcp
+ mode. Applets of type 'tcp' can be called from anywhre.
Here, an exemple of service registration. the service just send an 'Hello world'
as an http response.
@@ -475,6 +499,10 @@
set the value *value* associated to the key *key* in the map referenced by
*filename*.
+ :param string filename: the Map reference
+ :param string key: the key to set or replace
+ :param string value: the associated value
+
.. js:function:: core.sleep(int seconds)
**context**: body, init, task, action
@@ -489,7 +517,7 @@
This function returns a new object of a *socket* class.
- :returns: A socket class object.
+ :returns: A :ref:`socket_class` object.
.. js:function:: core.done(data)
@@ -511,6 +539,8 @@
Give back the hand at the HAProxy scheduler. It is used when the LUA
processing consumes a lot of processing time.
+.. _fetches_class:
+
Fetches class
=============
@@ -520,6 +550,9 @@
HAProxy "configuration.txt" documentation for more information about her
usage. they are the chapters 7.3.2 to 7.3.6.
+ **warning** some sample fetches are not available in some context. These
+ limitations are specified in this documentation when theire useful.
+
:see: TXN.f
:see: TXN.sf
@@ -537,12 +570,14 @@
.. code-block:: lua
- function action(txn)
- -- Get source IP
- local clientip = txn.f:src()
- end
+ function action(txn)
+ -- Get source IP
+ local clientip = txn.f:src()
+ end
..
+.. _converters_class:
+
Converters class
================
@@ -565,6 +600,8 @@
* turn to lower or upper chars,
* deal with stick tables.
+.. _channel_class:
+
Channel class
=============
@@ -673,6 +710,8 @@
:param class_channel channel: The manipulated Channel.
:param integer int: The amount of data which will be forwarded.
+
+.. _http_class:
HTTP class
==========
@@ -689,6 +728,19 @@
:returns: array of headers.
:see: HTTP.res_get_headers()
+ This is the form of the returned array:
+
+.. code-block:: lua
+
+ HTTP:req_get_headers()['<header-name>'][<header-index>] = "<header-value>"
+
+ local hdr = HTTP:req_get_headers()
+ hdr["host"][0] = "www.test.com"
+ hdr["accept"][0] = "audio/basic q=1"
+ hdr["accept"][1] = "audio/*, q=0.2"
+ hdr["accept"][2] = "*/*, q=0.1"
+..
+
.. js:function:: HTTP.res_get_headers(http)
Returns an array containing all the response headers.
@@ -697,6 +749,19 @@
:returns: array of headers.
:see: HTTP.req_get_headers()
+ This is the form of the returned array:
+
+.. code-block:: lua
+
+ HTTP:res_get_headers()['<header-name>'][<header-index>] = "<header-value>"
+
+ local hdr = HTTP:req_get_headers()
+ hdr["host"][0] = "www.test.com"
+ hdr["accept"][0] = "audio/basic q=1"
+ hdr["accept"][1] = "audio/*, q=0.2"
+ hdr["accept"][2] = "*.*, q=0.1"
+..
+
.. js:function:: HTTP.req_add_header(http, name, value)
Appends an HTTP header field in the request whose name is
@@ -854,6 +919,8 @@
:param class_http http: The related http object.
:param integer status: The new response status code.
+.. _txn_class:
+
TXN class
=========
@@ -871,32 +938,46 @@
.. js:attribute:: TXN.c
+ :returns: An :ref:`converters_class`.
+
This attribute contains a Converters class object.
.. js:attribute:: TXN.sc
+ :returns: An :ref:`converters_class`.
+
This attribute contains a Converters class object. The functions of
this object returns always a string.
.. js:attribute:: TXN.f
+ :returns: An :ref:`fetches_class`.
+
This attribute contains a Fetches class object.
.. js:attribute:: TXN.sf
+ :returns: An :ref:`fetches_class`.
+
This attribute contains a Fetches class object. The functions of
this object returns always a string.
.. js:attribute:: TXN.req
+ :returns: An :ref:`channel_class`.
+
This attribute contains a channel class object for the request buffer.
.. js:attribute:: TXN.res
+ :returns: An :ref:`channel_class`.
+
This attribute contains a channel class object for the response buffer.
.. js:attribute:: TXN.http
+ :returns: An :ref:`http_class`.
+
This attribute contains an HTTP class object. It is avalaible only if the
proxy has the "mode http" enabled.
@@ -937,9 +1018,9 @@
.. code-block:: lua
- function Debug(txn, msg)
- TXN.log(txn, core.debug, msg)
- end
+ function Debug(txn, msg)
+ TXN.log(txn, core.debug, msg)
+ end
..
.. js:function:: TXN.Info(txn, msg)
@@ -950,9 +1031,9 @@
.. code-block:: lua
- function Debug(txn, msg)
- TXN.log(txn, core.info, msg)
- end
+ function Debug(txn, msg)
+ TXN.log(txn, core.info, msg)
+ end
..
.. js:function:: TXN.Warning(txn, msg)
@@ -963,9 +1044,9 @@
.. code-block:: lua
- function Debug(txn, msg)
- TXN.log(txn, core.warning, msg)
- end
+ function Debug(txn, msg)
+ TXN.log(txn, core.warning, msg)
+ end
..
.. js:function:: TXN.Alert(txn, msg)
@@ -976,9 +1057,9 @@
.. code-block:: lua
- function Debug(txn, msg)
- TXN.log(txn, core.alert, msg)
- end
+ function Debug(txn, msg)
+ TXN.log(txn, core.alert, msg)
+ end
..
.. js:function:: TXN.get_priv(txn)
@@ -1059,6 +1140,8 @@
:param class_txn txn: The class txn object containing the data.
:param integer mark: The mark value.
+.. _socket_class:
+
Socket class
============
@@ -1228,6 +1311,8 @@
:param class_socket socket: Is the manipulated Socket.
:param integer value: The timeout value.
+.. _map_class:
+
Map class
=========
@@ -1238,33 +1323,33 @@
.. code-block:: lua
- default = "usa"
+ default = "usa"
- -- Create and load map
- geo = Map.new("geo.map", Map.ip);
+ -- Create and load map
+ geo = Map.new("geo.map", Map.ip);
- -- Create new fetch that returns the user country
- core.register_fetches("country", function(txn)
- local src;
- local loc;
+ -- Create new fetch that returns the user country
+ core.register_fetches("country", function(txn)
+ local src;
+ local loc;
- src = txn.f:fhdr("x-forwarded-for");
- if (src == nil) then
- src = txn.f:src()
- if (src == nil) then
- return default;
- end
- end
+ src = txn.f:fhdr("x-forwarded-for");
+ if (src == nil) then
+ src = txn.f:src()
+ if (src == nil) then
+ return default;
+ end
+ end
- -- Perform lookup
- loc = geo:lookup(src);
+ -- Perform lookup
+ loc = geo:lookup(src);
- if (loc == nil) then
- return default;
- end
+ if (loc == nil) then
+ return default;
+ end
- return loc;
- end);
+ return loc;
+ end);
.. js:attribute:: Map.int
@@ -1347,8 +1432,10 @@
:param string str: Is the string used as key.
:returns: a string containing the result or empty string if no match.
+.. _applethttp_class:
+
AppletHTTP class
-===============
+================
.. js:class:: AppletHTTP
@@ -1359,6 +1446,7 @@
This is an hello world sample code:
.. code-block:: lua
+
core.register_service("hello-world", "http", function(applet)
local response = "Hello World !"
applet:set_status(200)
@@ -1368,9 +1456,94 @@
applet:send(response)
end)
+.. js:attribute:: AppletHTTP.c
+
+ :returns: A :ref:`converters_class`
+
+ This attribute contains a Converters class object.
+
+.. js:attribute:: AppletHTTP.sc
+
+ :returns: A :ref:`converters_class`
+
+ This attribute contains a Converters class object. The
+ functions of this object returns always a string.
+
+.. js:attribute:: AppletHTTP.f
+
+ :returns: A :ref:`fetches_class`
+
+ This attribute contains a Fetches class object. Note that the
+ applet execution place cannot access to a valid HAProxy core HTTP
+ transaction, so some sample fecthes related to the HTTP dependant
+ values (hdr, path, ...) are not available.
+
+.. js:attribute:: AppletHTTP.sf
+
+ :returns: A :ref:`fetches_class`
+
+ This attribute contains a Fetches class object. The functions of
+ this object returns always a string. Note that the applet
+ execution place cannot access to a valid HAProxy core HTTP
+ transaction, so some sample fecthes related to the HTTP dependant
+ values (hdr, path, ...) are not available.
+
+.. js:attribute:: AppletHTTP.method (string)
+
+ :returns: string
+
+ The attribute method returns a string containing the HTTP
+ method.
+
+.. js:attribute:: AppletHTTP.version
+
+ :returns: string
+
+ The attribute version, returns a string containing the HTTP
+ request version.
+
+.. js:attribute:: AppletHTTP.path
+
+ :returns: string
+
+ The attribute path returns a string containing the HTTP
+ request path.
+
+.. js:attribute:: AppletHTTP.qs
+
+ :returns: string
+
+ The attribute qs returns a string containing the HTTP
+ request query string.
+
+.. js:attribute:: AppletHTTP.length
+
+ :returns: integer
+
+ The attribute length returns an integer containing the HTTP
+ body length.
.. js:attribute:: AppletHTTP.headers
+ :returns: array
+
+ The attribute headers returns an array containing the HTTP
+ headers. The header names are always in lower case. As the header name can be
+ encountered more than once in each request, the value is indexed with 0 as
+ first index value. The array have this form:
+
+.. code-block:: lua
+
+ AppletHTTP.headers['<header-name>'][<header-index>] = "<header-value>"
+
+ AppletHTTP.headers["host"][0] = "www.test.com"
+ AppletHTTP.headers["accept"][0] = "audio/basic q=1"
+ AppletHTTP.headers["accept"][1] = "audio/*, q=0.2"
+ AppletHTTP.headers["accept"][2] = "*.*, q=0.1"
+..
+
+.. js:attribute:: AppletHTTP.headers
+
Contains an array containing all the request headers.
.. js:function:: AppletHTTP.set_status(code)
@@ -1422,6 +1595,8 @@
:param string msg: the message to send.
+.. _applettcp_class:
+
AppletTCP class
===============
@@ -1431,6 +1606,31 @@
can be registered with the *core.register_service()* function. They are used
for processing a tcp stream like a server in back of HAProxy.
+.. js:attribute:: AppletTCP.c
+
+ :returns: A :ref:`converters_class`
+
+ This attribute contains a Converters class object.
+
+.. js:attribute:: AppletTCP.sc
+
+ :returns: A :ref:`converters_class`
+
+ This attribute contains a Converters class object. The
+ functions of this object returns always a string.
+
+.. js:attribute:: AppletTCP.f
+
+ :returns: A :ref:`fetches_class`
+
+ This attribute contains a Fetches class object.
+
+.. js:attribute:: AppletTCP.sf
+
+ :returns: A :ref:`fetches_class`
+
+ This attribute contains a Fetches class object.
+
.. js:function:: AppletTCP.getline()
This function returns a string containing one line from the stream. If the