Adding upstream version 2.9.5.upstream/2.9.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 4941 insertions, 0 deletions

diff --git a/doc/lua-api/Makefile b/doc/lua-api/Makefile
new file mode 100644
index 0000000..b21857d
--- /dev/null
+++ b/doc/lua-api/Makefile
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/haproxy-lua.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/haproxy-lua.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/haproxy-lua"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/haproxy-lua"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/doc/lua-api/_static/channel.fig b/doc/lua-api/_static/channel.fig
new file mode 100644
index 0000000..8a6c0a1
--- /dev/null
+++ b/doc/lua-api/_static/channel.fig
@@ -0,0 +1,55 @@
+#FIG 3.2  Produced by xfig version 3.2.5b
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 1 0 1 0 7 50 -1 -1 0.000 1 0.0000 4500 1620 1260 585 4500 1620 5760 2205
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 8
+	 1170 1350 1170 1890 2790 1890 2790 2070 3240 1620 2790 1170
+	 2790 1350 1170 1350
+2 3 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 8
+	 5760 1350 5760 1890 7380 1890 7380 2070 7830 1620 7380 1170
+	 7380 1350 5760 1350
+2 1 1 1 0 7 50 -1 -1 1.000 0 0 -1 1 0 2
+	5 1 1.00 60.00 120.00
+	 6210 540 6210 1440
+2 1 1 1 0 7 50 -1 -1 1.000 0 0 -1 1 0 2
+	5 1 1.00 60.00 120.00
+	 6210 2340 6210 1800
+2 1 1 1 0 7 50 -1 -1 1.000 0 0 -1 1 0 2
+	5 1 1.00 60.00 120.00
+	 1350 2520 1350 1800
+2 1 1 1 0 7 50 -1 -1 1.000 0 0 -1 1 0 2
+	5 1 1.00 60.00 120.00
+	 1350 360 1350 1440
+3 0 1 1 0 7 50 -1 -1 1.000 0 0 1 5
+	5 1 1.00 60.00 120.00
+	 2970 1665 3105 1125 3330 900 3600 765 3915 720
+	 0.000 1.000 1.000 1.000 0.000
+3 0 1 1 0 7 50 -1 -1 1.000 0 0 1 5
+	5 1 1.00 60.00 120.00
+	 6030 1665 5895 1125 5670 900 5400 765 5040 720
+	 0.000 1.000 1.000 1.000 0.000
+4 2 0 50 -1 16 12 0.0000 4 195 750 1080 1665 producer\001
+4 1 0 50 -1 16 12 0.0000 4 195 1785 4500 1575 HAProxy processing\001
+4 1 0 50 -1 16 12 0.0000 4 195 1260 4500 1815 (including Lua)\001
+4 0 0 50 -1 16 12 0.0000 4 105 855 7920 1665 consumer\001
+4 0 0 50 -1 12 12 0.0000 4 150 600 1440 2205 set()\001
+4 0 0 50 -1 12 12 0.0000 4 165 960 1440 2400 append()\001
+4 0 0 50 -1 16 12 0.0000 4 150 1260 1260 2700 write functions\001
+4 0 0 50 -1 16 12 0.0000 4 150 1230 1260 315 read functions\001
+4 0 0 50 -1 12 12 0.0000 4 165 600 1440 540 dup()\001
+4 0 0 50 -1 12 12 0.0000 4 165 600 1440 735 get()\001
+4 0 0 50 -1 12 12 0.0000 4 165 1200 1440 930 get_line()\001
+4 0 0 50 -1 12 12 0.0000 4 165 1440 1440 1125 get_in_len()\001
+4 1 0 50 -1 12 12 0.0000 4 150 1080 4500 765 forward()\001
+4 0 0 50 -1 16 12 0.0000 4 150 1260 6120 495 write functions\001
+4 0 0 50 -1 12 12 0.0000 4 150 720 6300 1110 send()\001
+4 0 0 50 -1 12 12 0.0000 4 165 1560 6255 2205 get_out_len()\001
+4 0 0 50 -1 16 12 0.0000 4 150 1230 6120 2520 read functions\001
+4 1 0 50 -1 16 12 0.0000 4 150 1650 4500 315 both side functions\001
+4 1 0 50 -1 12 12 0.0000 4 150 1080 4500 540 is_full()\001
diff --git a/doc/lua-api/_static/channel.png b/doc/lua-api/_static/channel.png
new file mode 100644
index 0000000..e12a26e
--- /dev/null
+++ b/doc/lua-api/_static/channel.png
diff --git a/doc/lua-api/conf.py b/doc/lua-api/conf.py
new file mode 100644
index 0000000..fd7e0ee
--- /dev/null
+++ b/doc/lua-api/conf.py
@@ -0,0 +1,242 @@
+# -*- coding: utf-8 -*-
+#
+# haproxy-lua documentation build configuration file, created by
+# sphinx-quickstart on Tue Mar 10 11:15:09 2015.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'haproxy-lua'
+copyright = u'2015, Thierry FOURNIER'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'haproxy-luadoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'haproxy-lua.tex', u'haproxy-lua Documentation',
+   u'Thierry FOURNIER', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'haproxy-lua', u'haproxy-lua Documentation',
+     [u'Thierry FOURNIER'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'haproxy-lua', u'haproxy-lua Documentation',
+   u'Thierry FOURNIER', 'haproxy-lua', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
new file mode 100644
index 0000000..e8df63e
--- /dev/null
+++ b/doc/lua-api/index.rst
@@ -0,0 +1,4491 @@
+.. toctree::
+   :maxdepth: 2
+
+
+How Lua runs in HAProxy
+=======================
+
+HAProxy Lua running contexts
+----------------------------
+
+The Lua code executed in HAProxy can be processed in 2 main modes. The first one
+is the **initialisation mode**, and the second is the **runtime mode**.
+
+* In the **initialisation mode**, we can perform DNS solves, but we cannot
+  perform socket I/O. In this initialisation mode, HAProxy still blocked during
+  the execution of the Lua program.
+
+* In the **runtime mode**, we cannot perform DNS solves, but we can use sockets.
+  The execution of the Lua code is multiplexed with the requests processing, so
+  the Lua code seems to be run in blocking, but it is not the case.
+
+The Lua code is loaded in one or more files. These files contains main code and
+functions. Lua has 8 execution contexts.
+
+1. The Lua file **body context**. It is executed during the load of the Lua file
+   in the HAProxy `[global]` section with the directive `lua-load`. It is
+   executed in initialisation mode. This section is use for configuring Lua
+   bindings in HAProxy.
+
+2. The Lua **init context**. It is a Lua function executed just after the
+   HAProxy configuration parsing. The execution is in initialisation mode. In
+   this context the HAProxy environment are already initialized. It is useful to
+   check configuration, or initializing socket connections or tasks. These
+   functions are declared in the body context with the Lua function
+   `core.register_init()`. The prototype of the function is a simple function
+   without return value and without parameters, like this: `function fcn()`.
+
+3. The Lua **task context**. It is a Lua function executed after the start
+   of the HAProxy scheduler, and just after the declaration of the task with the
+   Lua function `core.register_task()`. This context can be concurrent with the
+   traffic processing. It is executed in runtime mode. The prototype of the
+   function is a simple function without return value and without parameters,
+   like this: `function fcn()`.
+
+4. The **action context**. It is a Lua function conditionally executed. These
+   actions are registered by the Lua directives "`core.register_action()`". The
+   prototype of the Lua called function is a function with doesn't returns
+   anything and that take an object of class TXN as entry. `function fcn(txn)`.
+
+5. The **sample-fetch context**. This function takes a TXN object as entry
+   argument and returns a string. These types of function cannot execute any
+   blocking function. They are useful to aggregate some of original HAProxy
+   sample-fetches and return the result. The prototype of the function is
+   `function string fcn(txn)`. These functions can be registered with the Lua
+   function `core.register_fetches()`. Each declared sample-fetch is prefixed by
+   the string "lua.".
+
+   .. note::
+      It is possible that this function cannot found the required data in the
+      original HAProxy sample-fetches, in this case, it cannot return the
+      result. This case is not yet supported
+
+6. The **converter context**. It is a Lua function that takes a string as input
+   and returns another string as output. These types of function are stateless,
+   it cannot access to any context. They don't execute any blocking function.
+   The call prototype is `function string fcn(string)`. This function can be
+   registered with the Lua function `core.register_converters()`. Each declared
+   converter is prefixed by the string "lua.".
+
+7. The **filter context**: It is a Lua object based on a class defining filter
+   callback functions. Lua filters are registered using
+   `core.register_filter()`. Each declared filter is prefixed by the string
+   "lua.".
+
+8. The **event context**: Inside a function that handles events subscribed
+   through `core.event_sub()` or `Server.event_sub()`.
+
+
+HAProxy Lua Hello world
+-----------------------
+
+HAProxy configuration file (`hello_world.conf`):
+
+::
+
+    global
+       lua-load hello_world.lua
+
+    listen proxy
+       bind 127.0.0.1:10001
+       tcp-request inspect-delay 1s
+       tcp-request content use-service lua.hello_world
+
+HAProxy Lua file (`hello_world.lua`):
+
+.. code-block:: lua
+
+    core.register_service("hello_world", "tcp", function(applet)
+       applet:send("hello world\n")
+    end)
+
+How to start HAProxy for testing this configuration:
+
+::
+
+    ./haproxy -f hello_world.conf
+
+On other terminal, you can test with telnet:
+
+::
+
+    #:~ telnet 127.0.0.1 10001
+    hello world
+
+Usage of load parameters
+------------------------
+
+HAProxy lua-load(-per-thread) directives allow a list of parameters after
+the lua file name. These parameters are accessible through an array of args
+using this code `local args = table.pack(...)` in the body of loaded file.
+
+Below, a new version of the hello world using load parameters
+
+HAProxy configuration file (`hello_world.conf`):
+
+::
+
+    global
+       lua-load hello_world.lua "this is not an hello world"
+
+    listen proxy
+       bind 127.0.0.1:10001
+       tcp-request inspect-delay 1s
+       tcp-request content use-service lua.hello_world
+
+HAProxy Lua file (`hello_world.lua`):
+
+.. code-block:: lua
+
+    local args = table.pack(...)
+
+    core.register_service("hello_world", "tcp", function(applet)
+       applet:send(args[1] .. "\n")
+    end)
+
+
+Core class
+==========
+
+.. js:class:: core
+
+   The "core" class contains all the HAProxy core functions. These function are
+   useful for the controlling of the execution flow, registering hooks,
+   manipulating global maps or ACL, ...
+
+   "core" class is basically provided with HAProxy. No `require` line is
+   required to uses these function.
+
+   The "core" class is static, it is not possible to create a new object of this
+   type.
+
+.. 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:attribute:: core.proxies
+
+  **context**: init, task, action, sample-fetch, converter
+
+  This attribute is a table of declared proxies (frontend and backends). Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by proxy name, and each entry is of type :ref:`proxy_class`.
+
+  .. Warning::
+     if you declared a frontend and backend with the same name, only one of
+     them will be listed.
+
+  :see: :js:attr:`core.backends`
+  :see: :js:attr:`core.frontends`
+
+.. js:attribute:: core.backends
+
+  **context**: init, task, action, sample-fetch, converter
+
+  This attribute is a table of declared proxies with backend capability. Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by the backend name, and each entry is of type :ref:`proxy_class`.
+
+  :see: :js:attr:`core.proxies`
+  :see: :js:attr:`core.frontends`
+
+.. js:attribute:: core.frontends
+
+  **context**: init, task, action, sample-fetch, converter
+
+  This attribute is a table of declared proxies with frontend capability. Each
+  proxy give an access to his list of listeners and servers. The table is
+  indexed by the frontend name, and each entry is of type :ref:`proxy_class`.
+
+  :see: :js:attr:`core.proxies`
+  :see: :js:attr:`core.backends`
+
+.. js:attribute:: core.thread
+
+  **context**: task, action, sample-fetch, converter, applet
+
+  This variable contains the executing thread number starting at 1. 0 is a
+  special case for the common lua context. So, if thread is 0, Lua scope is
+  shared by all threads, otherwise the scope is dedicated to a single thread.
+  A program which needs to execute some parts exactly once regardless of the
+  number of threads can check that core.thread is 0 or 1.
+
+.. js:function:: core.log(loglevel, msg)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  This function sends a log. The log is sent, according with the HAProxy
+  configuration file, to the loggers relevant to the current context and/or
+  to stderr if it is allowed.
+
+  The exact behaviour depends on tune.lua.log.loggers and tune.lua.log.stderr.
+
+  :param integer loglevel: Is the log level associated with the message. It is a
+   number between 0 and 7.
+  :param string msg: The log content.
+  :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
+    :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
+    :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
+  :see: :js:func:`core.Debug`
+  :see: :js:func:`core.Info`
+  :see: :js:func:`core.Warning`
+  :see: :js:func:`core.Alert`
+
+.. js:function:: core.Debug(msg)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param string msg: The log content.
+  :see: :js:func:`core.log`
+
+  Does the same job than:
+
+.. code-block:: lua
+
+  function Debug(msg)
+    core.log(core.debug, msg)
+  end
+..
+
+.. js:function:: core.Info(msg)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param string msg: The log content.
+  :see: :js:func:`core.log`
+
+.. code-block:: lua
+
+  function Info(msg)
+    core.log(core.info, msg)
+  end
+..
+
+.. js:function:: core.Warning(msg)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param string msg: The log content.
+  :see: :js:func:`core.log`
+
+.. code-block:: lua
+
+  function Warning(msg)
+    core.log(core.warning, msg)
+  end
+..
+
+.. js:function:: core.Alert(msg)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param string msg: The log content.
+  :see: :js:func:`core.log`
+
+.. code-block:: lua
+
+  function Alert(msg)
+    core.log(core.alert, msg)
+  end
+..
+
+.. js:function:: core.add_acl(filename, key)
+
+  **context**: init, task, action, sample-fetch, converter
+
+  Add the ACL *key* in the ACLs list referenced by the file *filename*.
+
+  :param string filename: the filename that reference the ACL entries.
+  :param string key: the key which will be added.
+
+.. js:function:: core.del_acl(filename, key)
+
+  **context**: init, task, action, sample-fetch, converter
+
+  Delete the ACL entry referenced by the key *key* in the list of ACLs
+  referenced by *filename*.
+
+  :param string filename: the filename that reference the ACL entries.
+  :param string key: the key which will be deleted.
+
+.. js:function:: core.del_map(filename, key)
+
+  **context**: init, task, action, sample-fetch, converter
+
+  Delete the map entry indexed with the specified key in the list of maps
+  referenced by his filename.
+
+  :param string filename: the filename that reference the map entries.
+  :param string key: the key which will be deleted.
+
+.. js:function:: core.get_info()
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  Returns HAProxy core information. We can find information like the uptime,
+  the pid, memory pool usage, tasks number, ...
+
+  This information is also returned by the management socket via the command
+  "show info". See the management socket documentation for more information
+  about the content of these variables.
+
+  :returns: an array of values.
+
+.. js:function:: core.get_var()
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  Returns data stored in the variable <var> converter in Lua type.
+  This is limited to "proc." scoped variables.
+
+  :param string var: The variable name in "proc." scope according with the
+   HAProxy variable syntax.
+
+.. js:function:: core.now()
+
+  **context**: body, init, task, action
+
+  This function returns the current time. The time returned is fixed by the
+  HAProxy core and assures than the hour will be monotonic and that the system
+  call 'gettimeofday' will not be called too. The time is refreshed between each
+  Lua execution or resume, so two consecutive call to the function "now" will
+  probably returns the same result.
+
+  :returns: a table which contains two entries "sec" and "usec". "sec"
+   contains the current at the epoch format, and "usec" contains the
+   current microseconds.
+
+.. js:function:: core.http_date(date)
+
+  **context**: body, init, task, action
+
+  This function take a string representing http date, and returns an integer
+  containing the corresponding date with a epoch format. A valid http date
+  me respect the format IMF, RFC850 or ASCTIME.
+
+  :param string date: a date http-date formatted
+  :returns: integer containing epoch date
+  :see: :js:func:`core.imf_date`.
+  :see: :js:func:`core.rfc850_date`.
+  :see: :js:func:`core.asctime_date`.
+  :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
+
+.. js:function:: core.imf_date(date)
+
+  **context**: body, init, task, action
+
+  This function take a string representing IMF date, and returns an integer
+  containing the corresponding date with a epoch format.
+
+  :param string date: a date IMF formatted
+  :returns: integer containing epoch date
+  :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
+
+  The IMF format is like this:
+
+.. code-block:: text
+
+	Sun, 06 Nov 1994 08:49:37 GMT
+..
+
+.. js:function:: core.rfc850_date(date)
+
+  **context**: body, init, task, action
+
+  This function take a string representing RFC850 date, and returns an integer
+  containing the corresponding date with a epoch format.
+
+  :param string date: a date RFC859 formatted
+  :returns: integer containing epoch date
+  :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
+
+  The RFC850 format is like this:
+
+.. code-block:: text
+
+	Sunday, 06-Nov-94 08:49:37 GMT
+..
+
+.. js:function:: core.asctime_date(date)
+
+  **context**: body, init, task, action
+
+  This function take a string representing ASCTIME date, and returns an integer
+  containing the corresponding date with a epoch format.
+
+  :param string date: a date ASCTIME formatted
+  :returns: integer containing epoch date
+  :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
+
+  The ASCTIME format is like this:
+
+.. code-block:: text
+
+	Sun Nov  6 08:49:37 1994
+..
+
+.. js:function:: core.msleep(milliseconds)
+
+  **context**: body, init, task, action
+
+  The `core.msleep()` stops the Lua execution between specified milliseconds.
+
+  :param integer milliseconds: the required milliseconds.
+
+.. js:function:: core.register_action(name, actions, func [, nb_args])
+
+  **context**: body
+
+  Register a Lua function executed as action. All the registered action can be
+  used in HAProxy with the prefix "lua.". An action gets a TXN object class as
+  input.
+
+  :param string name: is the name of the action.
+  :param table actions: is a table of string describing the HAProxy actions
+   facilities where to expose the new action. Expected facilities  are:
+   'tcp-req', 'tcp-res', 'http-req', 'http-res', 'http-after-res'.
+  :param function func: is the Lua function called to work as an action.
+  :param integer nb_args: is the expected number of argument for the action.
+   By default the value is 0.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+  function(txn [, arg1 [, arg2]])
+..
+
+  * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
+            current request or TCP stream.
+
+  * **argX**: this is argument provided through the HAProxy configuration file.
+
+  Here, an example of action registration. The action just send an 'Hello world'
+  in the logs.
+
+.. code-block:: lua
+
+  core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
+     txn:Info("Hello world")
+  end)
+..
+
+  This example code is used in HAProxy configuration like this:
+
+::
+
+  frontend tcp_frt
+    mode tcp
+    tcp-request content lua.hello-world
+
+  frontend http_frt
+    mode http
+    http-request lua.hello-world
+
+..
+
+  A second example using arguments
+
+.. code-block:: lua
+
+  function hello_world(txn, arg)
+     txn:Info("Hello world for " .. arg)
+  end
+  core.register_action("hello-world", { "tcp-req", "http-req" }, hello_world, 2)
+
+..
+
+  This example code is used in HAProxy configuration like this:
+
+::
+
+  frontend tcp_frt
+    mode tcp
+    tcp-request content lua.hello-world everybody
+
+..
+
+.. js:function:: core.register_converters(name, func)
+
+  **context**: body
+
+  Register a Lua function executed as converter. All the registered converters
+  can be used in HAProxy with the prefix "lua.". A converter gets a string as
+  input and returns a string as output. The registered function can take up to 9
+  values as parameter. All the values are strings.
+
+  :param string name: is the name of the converter.
+  :param function func: is the Lua function called to work as converter.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+  function(str, [p1 [, p2 [, ... [, p5]]]])
+..
+
+  * **str** (*string*): this is the input value automatically converted in
+    string.
+  * **p1** .. **p5** (*string*): this is a list of string arguments declared in
+    the HAProxy configuration file. The number of arguments doesn't exceed 5.
+    The order and the nature of these is conventionally chosen by the
+    developer.
+
+.. js:function:: core.register_fetches(name, func)
+
+  **context**: body
+
+  Register a Lua function executed as sample fetch. All the registered sample
+  fetch can be used in HAProxy with the prefix "lua.". A Lua sample fetch
+  returns a string as output. The registered function can take up to 9 values as
+  parameter. All the values are strings.
+
+  :param string name: is the name of the sample fetch.
+  :param function func: is the Lua function called to work as sample fetch.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+    string function(txn, [p1 [, p2 [, ... [, p5]]]])
+..
+
+  * **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 HAProxy configuration file. The number of arguments doesn't exceed 5.
+    The order and the nature of these is conventionally chosen by the
+    developer.
+  * **Returns**: A string containing some data, or nil if the value cannot be
+    returned now.
+
+  lua example code:
+
+.. code-block:: lua
+
+    core.register_fetches("hello", function(txn)
+        return "hello"
+    end)
+..
+
+  HAProxy example configuration:
+
+::
+
+    frontend example
+       http-request redirect location /%[lua.hello]
+
+.. js:function:: core.register_filter(name, Flt, func)
+
+  **context**: body
+
+  Register a Lua function used to declare a filter. All the registered filters
+  can by used in HAProxy with the prefix "lua.".
+
+  :param string name: is the name of the filter.
+  :param table Flt: is a Lua class containing the filter definition (id, flags,
+   callbacks).
+  :param function func: is the Lua function called to create the Lua filter.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+  function(flt, args)
+..
+
+  * **flt** : Is a filter object based on the class provided in
+    :js:func:`core.register_filter()` function.
+
+  * **args**: Is a table of strings containing all arguments provided through
+    the HAProxy configuration file, on the filter line.
+
+  It must return the filter to use or nil to ignore it. Here, an example of
+  filter registration.
+
+.. code-block:: lua
+
+  core.register_filter("my-filter", MyFilter, function(flt, args)
+     flt.args = args -- Save arguments
+     return flt
+  end)
+..
+
+  This example code is used in HAProxy configuration like this:
+
+::
+
+  frontend http
+    mode http
+    filter lua.my-filter arg1 arg2 arg3
+
+..
+
+  :see: :js:class:`Filter`
+
+.. js:function:: core.register_service(name, mode, func)
+
+  **context**: body
+
+  Register a Lua function executed as a service. All the registered services
+  can be used in HAProxy with the prefix "lua.". A service gets an object class
+  as input according with the required mode.
+
+  :param string name: is the name of the service.
+  :param string mode: is string describing the required mode. Only 'tcp' or
+   'http' are allowed.
+  :param function func: is the Lua function called to work as service.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+  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`.
+
+  .. 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
+     a HTTP applet from a proxy in tcp mode. Applets of type 'tcp' can be
+     called from anywhere.
+
+  Here, an example of service registration. The service just send an
+  'Hello world' as an http response.
+
+.. code-block:: lua
+
+  core.register_service("hello-world", "http", function(applet)
+     local response = "Hello World !"
+     applet:set_status(200)
+     applet:add_header("content-length", string.len(response))
+     applet:add_header("content-type", "text/plain")
+     applet:start_response()
+     applet:send(response)
+  end)
+..
+
+  This example code is used in HAProxy configuration like this:
+
+::
+
+    frontend example
+       http-request use-service lua.hello-world
+
+.. js:function:: core.register_init(func)
+
+  **context**: body
+
+  Register a function executed after the configuration parsing. This is useful
+  to check any parameters.
+
+  :param function func: is the Lua function called to work as initializer.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+    function()
+..
+
+  It takes no input, and no output is expected.
+
+.. js:function:: core.register_task(func[, arg1[, arg2[, ...[, arg4]]]])
+
+  **context**: body, init, task, action, sample-fetch, converter, event
+
+  Register and start independent task. The task is started when the HAProxy
+  main scheduler starts. For example this type of tasks can be executed to
+  perform complex health checks.
+
+  :param function func: is the Lua function called to work as an async task.
+
+  Up to 4 optional arguments (all types supported) may be passed to the
+  function. (They will be passed as-is to the task function)
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+    function([arg1[, arg2[, ...[, arg4]]]])
+..
+
+  It takes up to 4 optional arguments (provided when registering), and no
+  output is expected.
+
+  See also :js:func:`core.queue` to dynamically pass data between main context
+  and tasks or even between tasks.
+
+.. js:function:: core.register_cli([path], usage, func)
+
+  **context**: body
+
+  Register a custom cli that will be available from haproxy stats socket.
+
+  :param array path: is the sequence of word for which the cli execute the Lua
+   binding.
+  :param string usage: is the usage message displayed in the help.
+  :param function func: is the Lua function called to handle the CLI commands.
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+    function(AppletTCP, [arg1, [arg2, [...]]])
+..
+
+  I/O are managed with the :ref:`applettcp_class` object. Args are given as
+  parameter. The args embed the registered path. If the path is declared like
+  this:
+
+.. code-block:: lua
+
+    core.register_cli({"show", "ssl", "stats"}, "Display SSL stats..", function(applet, arg1, arg2, arg3, arg4, arg5)
+	 end)
+..
+
+  And we execute this in the prompt:
+
+.. code-block:: text
+
+    > prompt
+    > show ssl stats all
+..
+
+  Then, arg1, arg2 and arg3 will contains respectively "show", "ssl" and
+  "stats".
+  arg4 will contain "all". arg5 contains nil.
+
+.. js:function:: core.set_nice(nice)
+
+  **context**: task, action, sample-fetch, converter
+
+  Change the nice of the current task or current session.
+
+  :param integer nice: the nice value, it must be between -1024 and 1024.
+
+.. js:function:: core.set_map(filename, key, value)
+
+  **context**: init, task, action, sample-fetch, converter
+
+  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
+
+  The `core.sleep()` functions stop the Lua execution between specified seconds.
+
+  :param integer seconds: the required seconds.
+
+.. js:function:: core.tcp()
+
+  **context**: init, task, action
+
+  This function returns a new object of a *socket* class.
+
+  :returns: A :ref:`socket_class` object.
+
+.. js:function:: core.httpclient()
+
+  **context**: init, task, action
+
+  This function returns a new object of a *httpclient* class.
+
+  :returns: A :ref:`httpclient_class` object.
+
+.. js:function:: core.concat()
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  This function returns a new concat object.
+
+  :returns: A :ref:`concat_class` object.
+
+.. js:function:: core.queue()
+
+  **context**: body, init, task, event, action, sample-fetch, converter
+
+  This function returns a new queue object.
+
+  :returns: A :ref:`queue_class` object.
+
+.. js:function:: core.done(data)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param any data: Return some data for the caller. It is useful with
+   sample-fetches and sample-converters.
+
+  Immediately stops the current Lua execution and returns to the caller which
+  may be a sample fetch, a converter or an action and returns the specified
+  value (ignored for actions and init). It is used when the LUA process finishes
+  its work and wants to give back the control to HAProxy without executing the
+  remaining code. It can be seen as a multi-level "return".
+
+.. js:function:: core.yield()
+
+  **context**: task, action, sample-fetch, converter
+
+  Give back the hand at the HAProxy scheduler. It is used when the LUA
+  processing consumes a lot of processing time.
+
+.. js:function:: core.parse_addr(address)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param network: is a string describing an ipv4 or ipv6 address and optionally
+   its network length, like this: "127.0.0.1/8" or "aaaa::1234/32".
+  :returns: a userdata containing network or nil if an error occurs.
+
+  Parse ipv4 or ipv6 addresses and its facultative associated network.
+
+.. js:function:: core.match_addr(addr1, addr2)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  :param addr1: is an address created with "core.parse_addr".
+  :param addr2: is an address created with "core.parse_addr".
+  :returns: boolean, true if the network of the addresses match, else returns
+   false.
+
+  Match two networks. For example "127.0.0.1/32" matches "127.0.0.0/8". The
+  order of network is not important.
+
+.. js:function:: core.tokenize(str, separators [, noblank])
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  This function is useful for tokenizing an entry, or splitting some messages.
+  :param string str: The string which will be split.
+  :param string separators: A string containing a list of separators.
+  :param boolean noblank: Ignore empty entries.
+  :returns: an array of string.
+
+  For example:
+
+.. code-block:: lua
+
+	local array = core.tokenize("This function is useful, for tokenizing an entry.", "., ", true)
+	print_r(array)
+..
+
+  Returns this array:
+
+.. code-block:: text
+
+	(table) table: 0x21c01e0 [
+	    1: (string) "This"
+	    2: (string) "function"
+	    3: (string) "is"
+	    4: (string) "useful"
+	    5: (string) "for"
+	    6: (string) "tokenizing"
+	    7: (string) "an"
+	    8: (string) "entry"
+	]
+..
+
+.. js:function:: core.event_sub(event_types, func)
+
+  **context**: body, init, task, action, sample-fetch, converter
+
+  Register a function that will be called on specific system events.
+
+  :param array event_types: array of string containing the event types you want
+   to subscribe to
+  :param function func: is the Lua function called when one of the subscribed
+   events occur.
+  :returns: A :ref:`event_sub_class` object.
+  :see: :js:func:`Server.event_sub()`.
+
+  List of available event types :
+
+   **SERVER** Family:
+
+    * **SERVER_ADD**: when a server is added
+    * **SERVER_DEL**: when a server is removed
+    * **SERVER_DOWN**: when a server state goes from UP to DOWN
+    * **SERVER_UP**: when a server state goes from DOWN to UP
+    * **SERVER_STATE**: when a server state changes
+    * **SERVER_ADMIN**: when a server administrative state changes
+    * **SERVER_CHECK**: when a server's check status change is reported.
+      Be careful when subscribing to this type since many events might be
+      generated.
+
+   .. Note::
+     Use **SERVER** in **event_types** to subscribe to all server events types
+     at once. Note that this should only be used for testing purposes since a
+     single event source could result in multiple events types being generated.
+     (e.g.: SERVER_STATE will always be generated for each SERVER_DOWN or
+     SERVER_UP)
+
+  The prototype of the Lua function used as argument is:
+
+.. code-block:: lua
+
+    function(event, event_data, sub, when)
+..
+
+  * **event** (*string*): the event type (one of the **event_types** specified
+    when subscribing)
+  * **event_data**: specific to each event family (For **SERVER** family,
+    a :ref:`server_event_class` object)
+  * **sub**: class to manage the subscription from within the event
+    (a :ref:`event_sub_class` object)
+  * **when**: timestamp corresponding to the date when the event was generated.
+    It is an integer representing the number of seconds elapsed since Epoch.
+    It may be provided as optional argument to `os.date()` lua function to
+    convert it to a string according to a given format string.
+
+  .. Warning::
+    The callback function will only be scheduled on the very same thread that
+    performed the subscription.
+
+    Moreover, each thread treats events sequentially. It means that if you
+    have, let's say SERVER_UP followed by a SERVER_DOWN in a short timelapse,
+    then the cb function will first be called with SERVER_UP, and once it's
+    done handling the event, the cb function will be called again with
+    SERVER_DOWN.
+
+    This is to ensure event consistency when it comes to logging / triggering
+    logic from lua.
+
+    Your lua cb function may yield if needed, but you're pleased to process the
+    event as fast as possible to prevent the event queue from growing up,
+    depending on the event flow that is expected for the given subscription.
+
+    To prevent abuses, if the event queue for the current subscription goes
+    over a certain amount of unconsumed events, the subscription will pause
+    itself automatically for as long as it takes for your handler to catch up.
+    This would lead to events being missed, so an error will be reported in the
+    logs to warn you about that.
+    This is not something you want to let happen too often, it may indicate
+    that you subscribed to an event that is occurring too frequently or/and
+    that your callback function is too slow to keep up the pace and you should
+    review it.
+
+    If you want to do some parallel processing because your callback functions
+    are slow: you might want to create subtasks from lua using
+    :js:func:`core.register_task()` from within your callback function to
+    perform the heavy job in a dedicated task and allow remaining events to be
+    processed more quickly.
+
+.. js:function:: core.disable_legacy_mailers()
+
+  **LEGACY**
+
+  **context**: body, init
+
+  Disable the sending of email alerts through the legacy email sending
+  function when mailers are used in the configuration.
+
+  Use this when sending email alerts directly from lua.
+
+  :see: :js:func:`Proxy.get_mailers()`
+
+.. _proxy_class:
+
+Proxy class
+============
+
+.. js:class:: Proxy
+
+  This class provides a way for manipulating proxy and retrieving information
+  like statistics.
+
+.. js:attribute:: Proxy.name
+
+  Contain the name of the proxy.
+
+  .. warning::
+     This attribute is now deprecated and will eventually be removed.
+     Please use :js:func:`Proxy.get_name()` function instead.
+
+.. js:function:: Proxy.get_name()
+
+  Returns the name of the proxy.
+
+.. js:attribute:: Proxy.uuid
+
+  Contain the unique identifier of the proxy.
+
+  .. warning::
+     This attribute is now deprecated and will eventually be removed.
+     Please use :js:func:`Proxy.get_uuid()` function instead.
+
+.. js:function:: Proxy.get_uuid()
+
+  Returns the unique identifier of the proxy.
+
+.. js:attribute:: Proxy.servers
+
+  Contain a table with the attached servers. The table is indexed by server
+  name, and each server entry is an object of type :ref:`server_class`.
+
+.. js:attribute:: Proxy.stktable
+
+  Contains a stick table object of type :ref:`sticktable_class` attached to the
+  proxy.
+
+.. js:attribute:: Proxy.listeners
+
+  Contain a table with the attached listeners. The table is indexed by listener
+  name, and each each listeners entry is an object of type
+  :ref:`listener_class`.
+
+.. js:function:: Proxy.pause(px)
+
+  Pause the proxy. See the management socket documentation for more information.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+
+.. js:function:: Proxy.resume(px)
+
+  Resume the proxy. See the management socket documentation for more
+  information.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+
+.. js:function:: Proxy.stop(px)
+
+  Stop the proxy. See the management socket documentation for more information.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+
+.. js:function:: Proxy.shut_bcksess(px)
+
+  Kill the session attached to a backup server. See the management socket
+  documentation for more information.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+
+.. js:function:: Proxy.get_cap(px)
+
+  Returns a string describing the capabilities of the proxy.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+  :returns: a string "frontend", "backend", "proxy" or "ruleset".
+
+.. js:function:: Proxy.get_mode(px)
+
+  Returns a string describing the mode of the current proxy.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+  :returns: a string "tcp", "http", "syslog" or "unknown"
+
+.. js:function:: Proxy.get_srv_act(px)
+
+  Returns the number of current active servers for the current proxy that are
+  eligible for LB.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+  :returns: an integer
+
+.. js:function:: Proxy.get_srv_bck(px)
+
+  Returns the number backup servers for the current proxy that are eligible
+  for LB.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+  :returns: an integer
+
+.. js:function:: Proxy.get_stats(px)
+
+  Returns a table containing the proxy statistics. The statistics returned are
+  not the same if the proxy is frontend or a backend.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+  :returns: a key/value table containing stats
+
+.. js:function:: Proxy.get_mailers(px)
+
+  **LEGACY**
+
+  Returns a table containing mailers config for the current proxy or nil
+  if mailers are not available for the proxy.
+
+  :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
+   proxy.
+  :returns: a :ref:`proxy_mailers_class` containing proxy mailers config
+
+.. _proxy_mailers_class:
+
+ProxyMailers class
+==================
+
+**LEGACY**
+
+.. js:class:: ProxyMailers
+
+  This class provides mailers config for a given proxy.
+
+  If sending emails directly from lua, please consider
+  :js:func:`core.disable_legacy_mailers()` to disable the email sending from
+  haproxy. (Or email alerts will be sent twice...)
+
+.. js:attribute:: ProxyMailers.track_server_health
+
+  Boolean set to true if the option "log-health-checks" is configured on
+  the proxy, meaning that all server checks event should trigger email alerts.
+
+.. js:attribute:: ProxyMailers.log_level
+
+  An integer, the maximum log level that triggers email alerts. It is a number
+  between 0 and 7 as defined by option "email-alert level".
+
+.. js:attribute:: ProxyMailers.mailservers
+
+  An array containing the list of mail servers that should receive email alerts.
+  Each array entry is a name:desc pair where desc represents the full server
+  address (including port) as described in haproxy's configuration file.
+
+.. js:attribute:: ProxyMailers.mailservers_timeout
+
+  An integer representing the maximum time in milliseconds to wait for the
+  email to be sent. See "timeout mail" directive from "mailers" section in
+  haproxy configuration file.
+
+.. js:attribute:: ProxyMailers.smtp_hostname
+
+  A string containing the hostname to use for the SMTP transaction.
+  (option "email-alert myhostname")
+
+.. js:attribute:: ProxyMailers.smtp_from
+
+  A string containing the "MAIL FROM" address to use for the SMTP transaction.
+  (option "email-alert from")
+
+.. js:attribute:: ProxyMailers.smtp_to
+
+  A string containing the "RCPT TO" address to use for the SMTP transaction.
+  (option "email-alert to")
+
+.. _server_class:
+
+Server class
+============
+
+.. js:class:: Server
+
+  This class provides a way for manipulating servers and retrieving information.
+
+.. js:attribute:: Server.name
+
+  Contain the name of the server.
+
+  .. warning::
+     This attribute is now deprecated and will eventually be removed.
+     Please use :js:func:`Server.get_name()` function instead.
+
+.. js:function:: Server.get_name(sv)
+
+  Returns the name of the server.
+
+.. js:attribute:: Server.puid
+
+  Contain the proxy unique identifier of the server.
+
+  .. warning::
+     This attribute is now deprecated and will eventually be removed.
+     Please use :js:func:`Server.get_puid()` function instead.
+
+.. js:function:: Server.get_puid(sv)
+
+  Returns the proxy unique identifier of the server.
+
+.. js:function:: Server.get_rid(sv)
+
+  Returns the rid (revision ID) of the server.
+  It is an unsigned integer that is set upon server creation. Value is derived
+  from a global counter that starts at 0 and is incremented each time one or
+  multiple server deletions are followed by a server addition (meaning that
+  old name/id reuse could occur).
+
+  Combining server name/id with server rid yields a process-wide unique
+  identifier.
+
+.. js:function:: Server.is_draining(sv)
+
+  Return true if the server is currently draining sticky connections.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: a boolean
+
+.. js:function:: Server.is_backup(sv)
+
+  Return true if the server is a backup server
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: a boolean
+
+.. js:function:: Server.is_dynamic(sv)
+
+  Return true if the server was instantiated at runtime (e.g.: from the cli)
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: a boolean
+
+.. js:function:: Server.get_cur_sess(sv)
+
+  Return the number of currently active sessions on the server
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: an integer
+
+.. js:function:: Server.get_pend_conn(sv)
+
+  Return the number of pending connections to the server
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: an integer
+
+.. js:function:: Server.set_maxconn(sv, weight)
+
+  Dynamically change the maximum connections of the server. See the management
+  socket documentation for more information about the format of the string.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :param string maxconn: A string describing the server maximum connections.
+
+.. js:function:: Server.get_maxconn(sv, weight)
+
+  This function returns an integer representing the server maximum connections.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: an integer.
+
+.. js:function:: Server.set_weight(sv, weight)
+
+  Dynamically change the weight of the server. See the management socket
+  documentation for more information about the format of the string.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :param string weight: A string describing the server weight.
+
+.. js:function:: Server.get_weight(sv)
+
+  This function returns an integer representing the server weight.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: an integer.
+
+.. js:function:: Server.set_addr(sv, addr[, port])
+
+  Dynamically change the address of the server. See the management socket
+  documentation for more information about the format of the string.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :param string addr: A string describing the server address.
+
+.. js:function:: Server.get_addr(sv)
+
+  Returns a string describing the address of the server.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: A string
+
+.. js:function:: Server.get_stats(sv)
+
+  Returns server statistics.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: a key/value table containing stats
+
+.. js:function:: Server.get_proxy(sv)
+
+  Returns the parent proxy to which the server belongs.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: a :ref:`proxy_class` or nil if not available
+
+.. js:function:: Server.shut_sess(sv)
+
+  Shutdown all the sessions attached to the server. See the management socket
+  documentation for more information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.set_drain(sv)
+
+  Drain sticky sessions. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.set_maint(sv)
+
+  Set maintenance mode. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.set_ready(sv)
+
+  Set normal mode. See the management socket documentation for more information
+  about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.check_enable(sv)
+
+  Enable health checks. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.check_disable(sv)
+
+  Disable health checks. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.check_force_up(sv)
+
+  Force health-check up. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.check_force_nolb(sv)
+
+  Force health-check nolb mode. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.check_force_down(sv)
+
+  Force health-check down. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.agent_enable(sv)
+
+  Enable agent check. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.agent_disable(sv)
+
+  Disable agent check. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.agent_force_up(sv)
+
+  Force agent check up. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.agent_force_down(sv)
+
+  Force agent check down. See the management socket documentation for more
+  information about this function.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+
+.. js:function:: Server.tracking(sv)
+
+  Check if the current server is tracking another server.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: A :ref:`server_class` which indicates the tracked server or nil if
+   the server doesn't track another one.
+
+.. js:function:: Server.get_trackers(sv)
+
+  Check if the current server is being tracked by other servers.
+
+  :param class_server sv: A :ref:`server_class` which indicates the manipulated
+   server.
+  :returns: An array of :ref:`server_class` which indicates the tracking
+   servers (might be empty)
+
+.. js:function:: Server.event_sub(sv, event_types, func)
+
+  Register a function that will be called on specific server events.
+  It works exactly like :js:func:`core.event_sub()` except that the subscription
+  will be performed within the server dedicated subscription list instead of the
+  global one.
+  (Your callback function will only be called for server events affecting sv)
+
+  See :js:func:`core.event_sub()` for function usage.
+
+  A key advantage to using :js:func:`Server.event_sub()` over
+  :js:func:`core.event_sub()` for servers is that :js:func:`Server.event_sub()`
+  allows you to be notified for servers events of a single server only.
+  It removes the needs for extra filtering in your callback function if you only
+  care about a single server, and also prevents useless wakeups.
+
+  For instance, if you want to be notified for UP/DOWN events on a given set of
+  servers, it is recommended to perform multiple per-server subscriptions since
+  it will be more efficient that doing a single global subscription that will
+  filter the received events.
+  Unless you really want to be notified for servers events of ALL servers of
+  course, which could make sense given you setup but should be avoided if you
+  have an important number of servers as it will add a significant load on your
+  haproxy process in case of multiple servers state change in a short amount of
+  time.
+
+  .. Note::
+     You may also combine :js:func:`core.event_sub()` with
+     :js:func:`Server.event_sub()`.
+
+     Also, don't forget that you can use :js:func:`core.register_task()` from
+     your callback function if needed. (ie: parallel work)
+
+  Here is a working example combining :js:func:`core.event_sub()` with
+  :js:func:`Server.event_sub()` and :js:func:`core.register_task()`
+  (This only serves as a demo, this is not necessarily useful to do so)
+
+.. code-block:: lua
+
+  core.event_sub({"SERVER_ADD"}, function(event, data, sub)
+    -- in the global event handler
+    if data["reference"] ~= nil then
+      print("Tracking new server: ", data["name"])
+      data["reference"]:event_sub({"SERVER_UP", "SERVER_DOWN"}, function(event, data, sub)
+        -- in the per-server event handler
+	if data["reference"] ~= nil then
+          core.register_task(function(server)
+            -- subtask to perform some async work (e.g.: HTTP API calls, sending emails...)
+            print("ASYNC: SERVER ", server:get_name(), " is ", event == "SERVER_UP" and "UP" or "DOWN")
+          end, data["reference"])
+        end
+      end)
+    end
+  end)
+
+..
+
+  In this example, we will first track global server addition events.
+  For each newly added server ("add server" on the cli), we will register a
+  UP/DOWN server subscription.
+  Then, the callback function will schedule the event handling in an async
+  subtask which will receive the server reference as an argument.
+
+.. _listener_class:
+
+Listener class
+==============
+
+.. js:function:: Listener.get_stats(ls)
+
+  Returns server statistics.
+
+  :param class_listener ls: A :ref:`listener_class` which indicates the
+   manipulated listener.
+  :returns: a key/value table containing stats
+
+.. _event_sub_class:
+
+EventSub class
+==============
+
+.. js:function:: EventSub.unsub()
+
+  End the subscription, the callback function will not be called again.
+
+.. _server_event_class:
+
+ServerEvent class
+=================
+
+.. js:class:: ServerEvent
+
+This class is provided with every **SERVER** events.
+
+See :js:func:`core.event_sub()` for more info.
+
+.. js:attribute:: ServerEvent.name
+
+  Contains the name of the server.
+
+.. js:attribute:: ServerEvent.puid
+
+  Contains the proxy-unique uid of the server
+
+.. js:attribute:: ServerEvent.rid
+
+  Contains the revision ID of the server
+
+.. js:attribute:: ServerEvent.proxy_name
+
+  Contains the name of the proxy to which the server belongs
+
+.. js:attribute:: ServerEvent.proxy_uuid
+
+  Contains the uuid of the proxy to which the server belongs
+
+.. js:attribute:: ServerEvent.reference
+
+  Reference to the live server (A :ref:`server_class`).
+
+  .. Warning::
+     Not available if the server was removed in the meantime.
+     (Will never be set for SERVER_DEL event since the server does not exist
+     anymore)
+
+.. js:attribute:: ServerEvent.state
+
+  A :ref:`server_event_state_class`
+
+  .. Note::
+     Only available for SERVER_STATE event
+
+.. js:attribute:: ServerEvent.admin
+
+  A :ref:`server_event_admin_class`
+
+  .. Note::
+     Only available for SERVER_ADMIN event
+
+.. js:attribute:: ServerEvent.check
+
+  A :ref:`server_event_checkres_class`
+
+  .. Note::
+     Only available for SERVER_CHECK event
+
+.. _server_event_checkres_class:
+
+ServerEventCheckRes class
+=========================
+
+.. js:class:: ServerEventCheckRes
+
+This class describes the result of a server's check.
+
+.. js:attribute:: ServerEventCheckRes.result
+
+  Effective check result.
+
+  Check result is a string and will be set to one of the following values:
+    - "FAILED": the check failed
+    - "PASSED": the check succeeded
+    - "CONDPASS": the check conditionally passed
+
+.. js:attribute:: ServerEventCheckRes.agent
+
+  Boolean set to true if the check is an agent check.
+  Else it is a health check.
+
+.. js:attribute:: ServerEventCheckRes.duration
+
+  Check's duration in milliseconds
+
+.. js:attribute:: ServerEventCheckRes.reason
+
+  Check's status. An array containing three fields:
+    - **short**: a string representing check status short name
+    - **desc**: a string representing check status description
+    - **code**: an integer, this extra information is provided for checks
+      that went through the data analysis stage (>= layer 5)
+
+.. js:attribute:: ServerEventCheckRes.health
+
+  An array containing values about check's health (integers):
+    - **cur**: current health counter:
+       - 0 to (**rise** - 1) = BAD
+       - **rise** to (**rise** + **fall** - 1) = GOOD
+    - **rise**: server will be considered as operational after **rise**
+      consecutive successful checks
+    - **fall**: server will be considered as dead after **fall** consecutive
+      unsuccessful checks
+
+.. _server_event_state_class:
+
+ServerEventState class
+======================
+
+.. js:class:: ServerEventState
+
+This class contains additional info related to **SERVER_STATE** event.
+
+.. js:attribute:: ServerEventState.admin
+
+  Boolean set to true if the server state change is due to an administrative
+  change. Else it is an operational change.
+
+.. js:attribute:: ServerEventState.check
+
+  A :ref:`server_event_checkres_class`, provided if the state change is
+  due to a server check (must be an operational change).
+
+.. js:attribute:: ServerEventState.cause
+
+  Printable state change cause. Might be empty.
+
+.. js:attribute:: ServerEventState.new_state
+
+  New server state due to operational or admin change.
+
+  It is a string that can be any of the following values:
+    - "STOPPED": The server is down
+    - "STOPPING": The server is up but soft-stopping
+    - "STARTING": The server is warming up
+    - "RUNNING": The server is fully up
+
+.. js:attribute:: ServerEventState.old_state
+
+  Previous server state prior to the operational or admin change.
+
+  Can be any value described in **new_state**, but they should differ.
+
+.. js:attribute:: ServerEventState.requeued
+
+  Number of connections that were requeued due to the server state change.
+
+  For a server going DOWN: it is the number of pending server connections
+  that are requeued to the backend (such connections will be redispatched
+  to any server that is suitable according to the configured load balancing
+  algorithm).
+
+  For a server doing UP: it is the number of pending connections on the
+  backend that may be redispatched to the server according to the load
+  balancing algorithm that is in use.
+
+.. _server_event_admin_class:
+
+ServerEventAdmin class
+======================
+
+.. js:class:: ServerEventAdmin
+
+This class contains additional info related to **SERVER_ADMIN** event.
+
+.. js:attribute:: ServerEventAdmin.cause
+
+  Printable admin state change cause. Might be empty.
+
+.. js:attribute:: ServerEventAdmin.new_admin
+
+  New server admin state due to the admin change.
+
+  It is an array of string containing a composition of following values:
+    - "**MAINT**": server is in maintenance mode
+    - "FMAINT": server is in forced maintenance mode (MAINT is also set)
+    - "IMAINT": server is in inherited maintenance mode (MAINT is also set)
+    - "RMAINT": server is in resolve maintenance mode (MAINT is also set)
+    - "CMAINT": server is in config maintenance mode (MAINT is also set)
+    - "**DRAIN**": server is in drain mode
+    - "FDRAIN": server is in forced drain mode (DRAIN is also set)
+    - "IDRAIN": server is in inherited drain mode (DRAIN is also set)
+
+.. js:attribute:: ServerEventAdmin.old_admin
+
+  Previous server admin state prior to the admin change.
+
+  Values are presented as in **new_admin**, but they should differ.
+  (Comparing old and new helps to find out the change(s))
+
+.. js:attribute:: ServerEventAdmin.requeued
+
+  Same as :js:attr:`ServerEventState.requeued` but when the requeue is due to
+  the server administrative state change.
+
+.. _queue_class:
+
+Queue class
+===========
+
+.. js:class:: Queue
+
+  This class provides a generic FIFO storage mechanism that may be shared
+  between multiple lua contexts to easily pass data between them, as stock
+  Lua doesn't provide easy methods for passing data between multiple coroutines.
+
+  inter-task example:
+
+.. code-block:: lua
+
+  -- script wide shared queue
+  local queue = core.queue()
+
+  -- master task
+  core.register_task(function()
+    -- send the date every second
+    while true do
+      queue:push(os.date("%c", core.now().sec))
+      core.sleep(1)
+    end
+  end)
+
+  -- worker task
+  core.register_task(function()
+    while true do
+      -- print the date sent by master
+      print(queue:pop_wait())
+    end
+  end)
+..
+
+  Of course, queue may also be used as a local storage mechanism.
+
+  Use :js:func:`core.queue` to get a new Queue object.
+
+.. js:function:: Queue.size(queue)
+
+  This function returns the number of items within the Queue.
+
+  :param class_queue queue: A :ref:`queue_class` to the current queue
+
+.. js:function:: Queue.push(queue, item)
+
+  This function pushes the item (may be of any type) to the queue.
+  Pushed item cannot be nil or invalid, or an error will be thrown.
+
+  :param class_queue queue: A :ref:`queue_class` to the current queue
+  :returns: boolean true for success and false for error
+
+.. js:function:: Queue.pop(queue)
+
+  This function immediately tries to pop an item from the queue.
+  It returns nil of no item is available at the time of the call.
+
+  :param class_queue queue: A :ref:`queue_class` to the current queue
+  :returns: the item at the top of the stack (any type) or nil if no items
+
+.. js:function:: Queue.pop_wait(queue)
+
+  **context**: task
+
+  This is an alternative to pop() that may be used within task contexts.
+
+  The call waits for data if no item is currently available. This may be
+  useful when used in a while loop to prevent cpu waste.
+
+  Note that this requires yielding, thus it is only available within contexts
+  that support yielding (mainly task context).
+
+  :param class_queue queue: A :ref:`queue_class` to the current queue
+  :returns: the item at the top of the stack (any type) or nil in case of error
+
+.. _concat_class:
+
+Concat class
+============
+
+.. js:class:: Concat
+
+  This class provides a fast way for string concatenation. The way using native
+  Lua concatenation like the code below is slow for some reasons.
+
+.. code-block:: lua
+
+  str = "string1"
+  str = str .. ", string2"
+  str = str .. ", string3"
+..
+
+  For each concatenation, Lua:
+  - allocates memory for the result,
+  - catenates the two string copying the strings in the new memory block,
+  - frees the old memory block containing the string which is no longer used.
+
+  This process does many memory move, allocation and free. In addition, the
+  memory is not really freed, it is just marked as unused and waits for the
+  garbage collector.
+
+  The Concat class provides an alternative way to concatenate strings. It uses
+  the internal Lua mechanism (it does not allocate memory), but it doesn't copy
+  the data more than once.
+
+  On my computer, the following loops spends 0.2s for the Concat method and
+  18.5s for the pure Lua implementation. So, the Concat class is about 1000x
+  faster than the embedded solution.
+
+.. code-block:: lua
+
+  for j = 1, 100 do
+    c = core.concat()
+    for i = 1, 20000 do
+      c:add("#####")
+    end
+  end
+..
+
+.. code-block:: lua
+
+  for j = 1, 100 do
+    c = ""
+    for i = 1, 20000 do
+      c = c .. "#####"
+    end
+  end
+..
+
+.. js:function:: Concat.add(concat, string)
+
+  This function adds a string to the current concatenated string.
+
+  :param class_concat concat: A :ref:`concat_class` which contains the currently
+   built string.
+  :param string string: A new string to concatenate to the current built
+   string.
+
+.. js:function:: Concat.dump(concat)
+
+  This function returns the concatenated string.
+
+  :param class_concat concat: A :ref:`concat_class` which contains the currently
+   built string.
+  :returns: the concatenated string
+
+.. _fetches_class:
+
+Fetches class
+=============
+
+.. js:class:: Fetches
+
+  This class contains a lot of internal HAProxy sample fetches. See the
+  HAProxy "configuration.txt" documentation for more information.
+  (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 they're useful.
+
+  :see: :js:attr:`TXN.f`
+  :see: :js:attr:`TXN.sf`
+
+  Fetches are useful to:
+
+  * get system time,
+  * get environment variable,
+  * get random numbers,
+  * know backend status like the number of users in queue or the number of
+    connections established,
+  * get client information like ip source or destination,
+  * deal with stick tables,
+  * fetch established SSL information,
+  * fetch HTTP information like headers or method.
+
+.. code-block:: lua
+
+  function action(txn)
+    -- Get source IP
+    local clientip = txn.f:src()
+  end
+..
+
+.. _converters_class:
+
+Converters class
+================
+
+.. js:class:: Converters
+
+  This class contains a lot of internal HAProxy sample converters. See the
+  HAProxy documentation "configuration.txt" for more information about her
+  usage. Its the chapter 7.3.1.
+
+  :see: :js:attr:`TXN.c`
+  :see: :js:attr:`TXN.sc`
+
+  Converters provides stateful transformation. They are useful to:
+
+  * convert input to base64,
+  * apply hash on input string (djb2, crc32, sdbm, wt6),
+  * format date,
+  * json escape,
+  * extract preferred language comparing two lists,
+  * turn to lower or upper chars,
+  * deal with stick tables.
+
+.. _channel_class:
+
+Channel class
+=============
+
+.. js:class:: Channel
+
+  **context**: action, sample-fetch, convert, filter
+
+  HAProxy uses two buffers for the processing of the requests. The first one is
+  used with the request data (from the client to the server) and the second is
+  used for the response data (from the server to the client).
+
+  Each buffer contains two types of data. The first type is the incoming data
+  waiting for a processing. The second part is the outgoing data already
+  processed. Usually, the incoming data is processed, after it is tagged as
+  outgoing data, and finally it is sent. The following functions provides tools
+  for manipulating these data in a buffer.
+
+  The following diagram shows where the channel class function are applied.
+
+  .. image:: _static/channel.png
+
+  .. warning::
+    It is not possible to read from the response in request action, and it is
+    not possible to read from the request channel in response action.
+
+  .. warning::
+    It is forbidden to alter the Channels buffer from HTTP contexts.  So only
+    :js:func:`Channel.input`, :js:func:`Channel.output`,
+    :js:func:`Channel.may_recv`, :js:func:`Channel.is_full` and
+    :js:func:`Channel.is_resp` can be called from a HTTP context.
+
+  All the functions provided by this class are available in the
+  **sample-fetches**, **actions** and **filters** contexts. For **filters**,
+  incoming data (offset and length) are relative to the filter. Some functions
+  may yield, but only for **actions**. Yield is not possible for
+  **sample-fetches**, **converters** and **filters**.
+
+.. js:function:: Channel.append(channel, string)
+
+  This function copies the string **string** at the end of incoming data of the
+  channel buffer. The function returns the copied length on success or -1 if
+  data cannot be copied.
+
+  Same that :js:func:`Channel.insert(channel, string, channel:input())`.
+
+  :param class_channel channel: The manipulated Channel.
+  :param string string: The data to copy at the end of incoming data.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: Channel.data(channel [, offset [, length]])
+
+  This function returns **length** bytes of incoming data from the channel
+  buffer, starting at the offset **offset**. The data are not removed from the
+  buffer.
+
+  By default, if no length is provided, all incoming data found, starting at the
+  given offset, are returned. If **length** is set to -1, the function tries to
+  retrieve a maximum of data and, if called by an action, it yields if
+  necessary. It also waits for more data if the requested length exceeds the
+  available amount of incoming data. Not providing an offset is the same as
+  setting it to 0. A positive offset is relative to the beginning of incoming
+  data of the channel buffer while negative offset is relative to the end.
+
+  If there is no incoming data and the channel can't receive more data, a 'nil'
+  value is returned.
+
+  :param class_channel channel: The manipulated Channel.
+  :param integer offset: *optional* The offset in incoming data to start to get
+   data. 0 by default. May be negative to be relative to the end of incoming
+   data.
+  :param integer length: *optional* The expected length of data to retrieve. All
+   incoming data by default. May be set to -1 to get a maximum of data.
+  :returns: a string containing the data found or nil.
+
+.. js:function:: Channel.forward(channel, length)
+
+  This function forwards **length** bytes of data from the channel buffer. If
+  the requested length exceeds the available amount of incoming data, and if
+  called by an action, the function yields, waiting for more data to forward. It
+  returns the amount of data forwarded.
+
+  :param class_channel channel: The manipulated Channel.
+  :param integer int: The amount of data to forward.
+
+.. js:function:: Channel.input(channel)
+
+  This function returns the length of incoming data in the channel buffer. When
+  called by a filter, this value is relative to the filter.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: an integer containing the amount of available bytes.
+
+.. js:function:: Channel.insert(channel, string [, offset])
+
+  This function copies the string **string** at the offset **offset** in
+  incoming data of the channel buffer. The function returns the copied length on
+  success or -1 if data cannot be copied.
+
+  By default, if no offset is provided, the string is copied in front of
+  incoming data. A positive offset is relative to the beginning of incoming data
+  of the channel buffer while negative offset is relative to their end.
+
+  :param class_channel channel: The manipulated Channel.
+  :param string string: The data to copy into incoming data.
+  :param integer offset: *optional* The offset in incoming data where to copy
+   data. 0 by default. May be negative to be relative to the end of incoming
+   data.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: Channel.is_full(channel)
+
+  This function returns true if the channel buffer is full.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: a boolean
+
+.. js:function:: Channel.is_resp(channel)
+
+  This function returns true if the channel is the response one.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: a boolean
+
+.. js:function:: Channel.line(channel [, offset [, length]])
+
+  This function parses **length** bytes of incoming data of the channel buffer,
+  starting at offset **offset**, and returns the first line found, including the
+  '\\n'.  The data are not removed from the buffer. If no line is found, all
+  data are returned.
+
+  By default, if no length is provided, all incoming data, starting at the given
+  offset, are evaluated. If **length** is set to -1, the function tries to
+  retrieve a maximum of data and, if called by an action, yields if
+  necessary. It also waits for more data if the requested length exceeds the
+  available amount of incoming data. Not providing an offset is the same as
+  setting it to 0. A positive offset is relative to the beginning of incoming
+  data of the channel buffer while negative offset is relative to the end.
+
+  If there is no incoming data and the channel can't receive more data, a 'nil'
+  value is returned.
+
+  :param class_channel channel: The manipulated Channel.
+  :param integer offset: *optional* The offset in incoming data to start to
+   parse data. 0 by default. May be negative to be relative to the end of
+   incoming data.
+  :param integer length: *optional* The length of data to parse. All incoming
+   data by default. May be set to -1 to get a maximum of data.
+  :returns: a string containing the line found or nil.
+
+.. js:function:: Channel.may_recv(channel)
+
+  This function returns true if the channel may still receive data.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: a boolean
+
+.. js:function:: Channel.output(channel)
+
+  This function returns the length of outgoing data of the channel buffer. When
+  called by a filter, this value is relative to the filter.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: an integer containing the amount of available bytes.
+
+.. js:function:: Channel.prepend(channel, string)
+
+  This function copies the string **string** in front of incoming data of the
+  channel buffer. The function returns the copied length on success or -1 if
+  data cannot be copied.
+
+  Same that :js:func:`Channel.insert(channel, string, 0)`.
+
+  :param class_channel channel: The manipulated Channel.
+  :param string string: The data to copy in front of incoming data.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: Channel.remove(channel [, offset [, length]])
+
+  This function removes **length** bytes of incoming data of the channel buffer,
+  starting at offset **offset**. This function returns number of bytes removed
+  on success.
+
+  By default, if no length is provided, all incoming data, starting at the given
+  offset, are removed. Not providing an offset is the same as setting it
+  to 0. A positive offset is relative to the beginning of incoming data of the
+  channel buffer while negative offset is relative to the end.
+
+  :param class_channel channel: The manipulated Channel.
+  :param integer offset: *optional* The offset in incoming data where to start
+   to remove data. 0 by default. May be negative to be relative to the end of
+   incoming data.
+  :param integer length: *optional* The length of data to remove. All incoming
+   data by default.
+  :returns: an integer containing the amount of bytes removed.
+
+.. js:function:: Channel.send(channel, string)
+
+  This function requires immediate send of the string **string**. It means the
+  string is copied at the beginning of incoming data of the channel buffer and
+  immediately forwarded. Unless if the connection is close, and if called by an
+  action, this function yields to copy and forward all the string.
+
+  :param class_channel channel: The manipulated Channel.
+  :param string string: The data to send.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: Channel.set(channel, string [, offset [, length]])
+
+  This function replaces **length** bytes of incoming data of the channel
+  buffer, starting at offset **offset**, by the string **string**. The function
+  returns the copied length on success or -1 if data cannot be copied.
+
+  By default, if no length is provided, all incoming data, starting at the given
+  offset, are replaced. Not providing an offset is the same as setting it
+  to 0. A positive offset is relative to the beginning of incoming data of the
+  channel buffer while negative offset is relative to the end.
+
+  :param class_channel channel: The manipulated Channel.
+  :param string string: The data to copy into incoming data.
+  :param integer offset: *optional* The offset in incoming data where to start
+   the data replacement. 0 by default. May be negative to be relative to the
+   end of incoming data.
+  :param integer length: *optional* The length of data to replace. All incoming
+   data by default.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: Channel.dup(channel)
+
+  **DEPRECATED**
+
+  This function returns all incoming data found in the channel buffer. The data
+  are not removed from the buffer and can be reprocessed later.
+
+  If there is no incoming data and the channel can't receive more data, a 'nil'
+  value is returned.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: a string containing all data found or nil.
+
+  .. warning::
+     This function is deprecated. :js:func:`Channel.data()` must be used
+     instead.
+
+.. js:function:: Channel.get(channel)
+
+  **DEPRECATED**
+
+  This function returns all incoming data found in the channel buffer and remove
+  them from the buffer.
+
+  If there is no incoming data and the channel can't receive more data, a 'nil'
+  value is returned.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: a string containing all the data found or nil.
+
+  .. warning::
+     This function is deprecated. :js:func:`Channel.data()` must be used to
+     retrieve data followed by a call to :js:func:`Channel:remove()` to remove
+     data.
+
+     .. code-block:: lua
+
+       local data = chn:data()
+       chn:remove(0, data:len())
+
+     ..
+
+.. js:function:: Channel.getline(channel)
+
+  **DEPRECATED**
+
+  This function returns the first line found in incoming data of the channel
+  buffer, including the '\\n'. The returned data are removed from the buffer. If
+  no line is found, and if called by an action, this function yields to wait for
+  more data, except if the channel can't receive more data. In this case all
+  data are returned.
+
+  If there is no incoming data and the channel can't receive more data, a 'nil'
+  value is returned.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: a string containing the line found or nil.
+
+  .. warning::
+     This function is deprecated. :js:func:`Channel.line()` must be used to
+     retrieve a line followed by a call to :js:func:`Channel:remove()` to remove
+     data.
+
+     .. code-block:: lua
+
+       local line = chn:line(0, -1)
+       chn:remove(0, line:len())
+
+     ..
+
+.. js:function:: Channel.get_in_len(channel)
+
+  **DEPRECATED**
+
+  This function returns the length of the input part of the buffer. When called
+  by a filter, this value is relative to the filter.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: an integer containing the amount of available bytes.
+
+  .. warning::
+     This function is deprecated. :js:func:`Channel.input()` must be used
+     instead.
+
+.. js:function:: Channel.get_out_len(channel)
+
+  **DEPRECATED**
+
+  This function returns the length of the output part of the buffer. When called
+  by a filter, this value is relative to the filter.
+
+  :param class_channel channel: The manipulated Channel.
+  :returns: an integer containing the amount of available bytes.
+
+  .. warning::
+     This function is deprecated. :js:func:`Channel.output()` must be used
+     instead.
+
+.. _http_class:
+
+HTTP class
+==========
+
+.. js:class:: HTTP
+
+   This class contain all the HTTP manipulation functions.
+
+.. js:function:: HTTP.req_get_headers(http)
+
+  Returns a table containing all the request headers.
+
+  :param class_http http: The related http object.
+  :returns: table of headers.
+  :see: :js:func:`HTTP.res_get_headers`
+
+  This is the form of the returned table:
+
+.. 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 a table containing all the response headers.
+
+  :param class_http http: The related http object.
+  :returns: table of headers.
+  :see: :js:func:`HTTP.req_get_headers`
+
+  This is the form of the returned table:
+
+.. 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 a HTTP header field in the request whose name is
+  specified in "name" and whose value is defined in "value".
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :param string value: The header value.
+  :see: :js:func:`HTTP.res_add_header`
+
+.. js:function:: HTTP.res_add_header(http, name, value)
+
+  Appends a HTTP header field in the response whose name is
+  specified in "name" and whose value is defined in "value".
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :param string value: The header value.
+  :see: :js:func:`HTTP.req_add_header`
+
+.. js:function:: HTTP.req_del_header(http, name)
+
+  Removes all HTTP header fields in the request whose name is
+  specified in "name".
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :see: :js:func:`HTTP.res_del_header`
+
+.. js:function:: HTTP.res_del_header(http, name)
+
+  Removes all HTTP header fields in the response whose name is
+  specified in "name".
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :see: :js:func:`HTTP.req_del_header`
+
+.. js:function:: HTTP.req_set_header(http, name, value)
+
+  This variable replace all occurrence of all header "name", by only
+  one containing the "value".
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :param string value: The header value.
+  :see: :js:func:`HTTP.res_set_header`
+
+  This function does the same work as the following code:
+
+.. code-block:: lua
+
+   function fcn(txn)
+      TXN.http:req_del_header("header")
+      TXN.http:req_add_header("header", "value")
+   end
+..
+
+.. js:function:: HTTP.res_set_header(http, name, value)
+
+  This function replaces all occurrence of all header "name", by only
+  one containing the "value".
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :param string value: The header value.
+  :see: :js:func:`HTTP.req_rep_header()`
+
+.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
+
+  Matches the regular expression in all occurrences of header field "name"
+  according to "regex", and replaces them with the "replace" argument. The
+  replacement value can contain back references like \1, \2, ... This
+  function works with the request.
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :param string regex: The match regular expression.
+  :param string replace: The replacement value.
+  :see: :js:func:`HTTP.res_rep_header()`
+
+.. js:function:: HTTP.res_rep_header(http, name, regex, string)
+
+  Matches the regular expression in all occurrences of header field "name"
+  according to "regex", and replaces them with the "replace" argument. The
+  replacement value can contain back references like \1, \2, ... This
+  function works with the request.
+
+  :param class_http http: The related http object.
+  :param string name: The header name.
+  :param string regex: The match regular expression.
+  :param string replace: The replacement value.
+  :see: :js:func:`HTTP.req_rep_header()`
+
+.. js:function:: HTTP.req_set_method(http, method)
+
+  Rewrites the request method with the parameter "method".
+
+  :param class_http http: The related http object.
+  :param string method: The new method.
+
+.. js:function:: HTTP.req_set_path(http, path)
+
+  Rewrites the request path with the "path" parameter.
+
+  :param class_http http: The related http object.
+  :param string path: The new path.
+
+.. js:function:: HTTP.req_set_query(http, query)
+
+  Rewrites the request's query string which appears after the first question
+  mark ("?") with the parameter "query".
+
+  :param class_http http: The related http object.
+  :param string query: The new query.
+
+.. js:function:: HTTP.req_set_uri(http, uri)
+
+  Rewrites the request URI with the parameter "uri".
+
+  :param class_http http: The related http object.
+  :param string uri: The new uri.
+
+.. js:function:: HTTP.res_set_status(http, status [, reason])
+
+  Rewrites the response status code with the parameter "code".
+
+  If no custom reason is provided, it will be generated from the status.
+
+  :param class_http http: The related http object.
+  :param integer status: The new response status code.
+  :param string reason: The new response reason (optional).
+
+.. _httpclient_class:
+
+HTTPClient class
+================
+
+.. js:class:: HTTPClient
+
+   The httpclient class allows issue of outbound HTTP requests through a simple
+   API without the knowledge of HAProxy internals.
+
+.. js:function:: HTTPClient.get(httpclient, request)
+.. js:function:: HTTPClient.head(httpclient, request)
+.. js:function:: HTTPClient.put(httpclient, request)
+.. js:function:: HTTPClient.post(httpclient, request)
+.. js:function:: HTTPClient.delete(httpclient, request)
+
+  Send a HTTP request and wait for a response. GET, HEAD PUT, POST and DELETE
+  methods can be used.
+  The HTTPClient will send asynchronously the data and is able to send and
+  receive more than HAProxy bufsize.
+
+  The HTTPClient interface is not able to decompress responses, it is not
+  recommended to send an Accept-Encoding in the request so the response is
+  received uncompressed.
+
+  :param class httpclient: Is the manipulated HTTPClient.
+  :param table request: Is a table containing the parameters of the request
+   that will be send.
+  :param string request.url: Is a mandatory parameter for the request that
+   contains the URL.
+  :param string request.body: Is an optional parameter for the request that
+   contains the body to send.
+  :param table request.headers: Is an optional parameter for the request that
+   contains the headers to send.
+  :param string request.dst: Is an optional parameter for the destination in
+   haproxy address format.
+  :param integer request.timeout: Optional timeout parameter, set a
+   "timeout server" on the connections.
+  :returns: Lua table containing the response
+
+
+.. code-block:: lua
+
+  local httpclient = core.httpclient()
+  local response = httpclient:post{url="http://127.0.0.1", body=body, dst="unix@/var/run/http.sock"}
+
+..
+
+.. code-block:: lua
+
+ response = {
+    status  = 400,
+    reason  = "Bad request",
+    headers = {
+        ["content-type"]  = { "text/html" },
+        ["cache-control"] = { "no-cache", "no-store" },
+    },
+    body = "<html><body><h1>invalid request<h1></body></html>",
+  }
+..
+
+
+.. _txn_class:
+
+TXN class
+=========
+
+.. js:class:: TXN
+
+  The txn class contain all the functions relative to the http or tcp
+  transaction (Note than a tcp stream is the same than a tcp transaction, but
+  a HTTP transaction is not the same than a tcp stream).
+
+  The usage of this class permits to retrieve data from the requests, alter it
+  and forward it.
+
+  All the functions provided by this class are available in the context
+  **sample-fetches**, **actions** and **filters**.
+
+.. 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 a HTTP class object. It is available only if the
+  proxy has the "mode http" enabled.
+
+.. js:attribute:: TXN.http_req
+
+  :returns: An :ref:`httpmessage_class`.
+
+  This attribute contains the request HTTPMessage class object. It is available
+  only if the proxy has the "mode http" enabled and only in the **filters**
+  context.
+
+.. js:attribute:: TXN.http_res
+
+  :returns: An :ref:`httpmessage_class`.
+
+  This attribute contains the response HTTPMessage class object. It is available
+  only if the proxy has the "mode http" enabled and only in the **filters**
+  context.
+
+.. js:function:: TXN.log(TXN, loglevel, msg)
+
+  This function sends a log. The log is sent, according with the HAProxy
+  configuration file, to the loggers relevant to the current context and/or
+  to stderr if it is allowed.
+
+  The exact behaviour depends on tune.lua.log.loggers and tune.lua.log.stderr.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param integer loglevel: Is the log level associated with the message. It is
+   a number between 0 and 7.
+  :param string msg: The log content.
+  :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
+    :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
+    :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
+  :see: :js:func:`TXN.deflog`
+  :see: :js:func:`TXN.Debug`
+  :see: :js:func:`TXN.Info`
+  :see: :js:func:`TXN.Warning`
+  :see: :js:func:`TXN.Alert`
+
+.. js:function:: TXN.deflog(TXN, msg)
+
+  Sends a log line with the default loglevel for the proxy associated with the
+  transaction.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string msg: The log content.
+  :see: :js:func:`TXN.log`
+
+.. js:function:: TXN.Debug(txn, msg)
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string msg: The log content.
+  :see: :js:func:`TXN.log`
+
+  Does the same job as:
+
+.. code-block:: lua
+
+  function Debug(txn, msg)
+    TXN.log(txn, core.debug, msg)
+  end
+..
+
+.. js:function:: TXN.Info(txn, msg)
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string msg: The log content.
+  :see: :js:func:`TXN.log`
+
+  Does the same job as:
+
+.. code-block:: lua
+
+  function Info(txn, msg)
+    TXN.log(txn, core.info, msg)
+  end
+..
+
+.. js:function:: TXN.Warning(txn, msg)
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string msg: The log content.
+  :see: :js:func:`TXN.log`
+
+  Does the same job as:
+
+.. code-block:: lua
+
+  function Warning(txn, msg)
+    TXN.log(txn, core.warning, msg)
+  end
+..
+
+.. js:function:: TXN.Alert(txn, msg)
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string msg: The log content.
+  :see: :js:func:`TXN.log`
+
+  Does the same job as:
+
+.. code-block:: lua
+
+  function Alert(txn, msg)
+    TXN.log(txn, core.alert, msg)
+  end
+..
+
+.. js:function:: TXN.get_priv(txn)
+
+  Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
+  function. If no data are stored, it returns a nil value.
+
+  :param class_txn txn: The class txn object containing the data.
+  :returns: the opaque data previously stored, or nil if nothing is
+   available.
+
+.. js:function:: TXN.set_priv(txn, data)
+
+  Store any data in the current HAProxy transaction. This action replaces the
+  old stored data.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param opaque data: The data which is stored in the transaction.
+
+.. js:function:: TXN.set_var(TXN, var, value[, ifexist])
+
+  Converts a Lua type in a HAProxy type and store it in a variable <var>.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :param type value: The value associated to the variable. The type can be
+   string or integer.
+  :param boolean ifexist: If this parameter is set to true the variable will
+   only be set if it was defined elsewhere (i.e. used within the configuration).
+   For global variables (using the "proc" scope), they will only be updated and
+   never created. It is highly recommended to always set this to true.
+
+.. js:function:: TXN.unset_var(TXN, var)
+
+  Unset the variable <var>.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+
+.. js:function:: TXN.get_var(TXN, var)
+
+  Returns data stored in the variable <var> converter in Lua type.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+
+.. js:function:: TXN.reply([reply])
+
+  Return a new reply object
+
+  :param table reply: A table containing info to initialize the reply fields.
+  :returns: A :ref:`reply_class` object.
+
+  The table used to initialized the reply object may contain following entries :
+
+  * status : The reply status code. the code 200 is used by default.
+  * reason : The reply reason. The reason corresponding to the status code is
+    used by default.
+  * headers : A list of headers, indexed by header name. Empty by default. For
+    a given name, multiple values are possible, stored in an ordered list.
+  * body : The reply body, empty by default.
+
+.. code-block:: lua
+
+  local reply = txn:reply{
+      status  = 400,
+      reason  = "Bad request",
+      headers = {
+          ["content-type"]  = { "text/html" },
+          ["cache-control"] = {"no-cache", "no-store" }
+      },
+      body = "<html><body><h1>invalid request<h1></body></html>"
+  }
+..
+  :see: :js:class:`Reply`
+
+.. js:function:: TXN.done(txn[, reply])
+
+  This function terminates processing of the transaction and the associated
+  session and optionally reply to the client for HTTP sessions.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param class_reply reply: The class reply object to return to the client.
+
+  This functions can be used when a critical error is detected or to terminate
+  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. If a reply object is provided, it must not exceed the buffer size once
+  converted into the internal HTTP representation. 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.
+
+.. code-block:: lua
+
+  local reply = txn:reply()
+  reply:set_status(400, "Bad request")
+  reply:add_header("content-type", "text/html")
+  reply:add_header("cache-control", "no-cache")
+  reply:add_header("cache-control", "no-store")
+  reply:set_body("<html><body><h1>invalid request<h1></body></html>")
+  txn:done(reply)
+..
+
+.. code-block:: lua
+
+   txn:done{
+       status  = 400,
+       reason  = "Bad request",
+       headers = {
+           ["content-type"]  = { "text/html" },
+           ["cache-control"] = { "no-cache", "no-store" },
+       },
+       body = "<html><body><h1>invalid request<h1></body></html>"
+   }
+..
+
+  .. warning::
+    It does not make sense to call this function from sample-fetches. In this
+    case the behavior is the same than core.done(): it finishes the Lua
+    execution. The transaction is really aborted only from an action registered
+    function.
+
+  :see: :js:func:`TXN.reply`, :js:class:`Reply`
+
+.. js:function:: TXN.set_loglevel(txn, loglevel)
+
+  Is used to change the log level of the current request. The "loglevel" must
+  be an integer between 0 and 7.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param integer loglevel: The required log level. This variable can be one of
+  :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
+    :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
+    :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
+
+.. js:function:: TXN.set_tos(txn, tos)
+
+  Is used to set the TOS or DSCP field value of packets sent to the client to
+  the value passed in "tos" on platforms which support this.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param integer tos: The new TOS os DSCP.
+
+.. js:function:: TXN.set_mark(txn, mark)
+
+  Is used to set the Netfilter MARK on all packets sent to the client to the
+  value passed in "mark" on platforms which support it.
+
+  :param class_txn txn: The class txn object containing the data.
+  :param integer mark: The mark value.
+
+.. js:function:: TXN.set_priority_class(txn, prio)
+
+  This function adjusts the priority class of the transaction. The value should
+  be within the range -2047..2047. Values outside this range will be
+  truncated.
+
+  See the HAProxy configuration.txt file keyword "http-request" action
+  "set-priority-class" for details.
+
+.. js:function:: TXN.set_priority_offset(txn, prio)
+
+  This function adjusts the priority offset of the transaction. The value
+  should be within the range -524287..524287. Values outside this range will be
+  truncated.
+
+  See the HAProxy configuration.txt file keyword "http-request" action
+  "set-priority-offset" for details.
+
+.. _reply_class:
+
+Reply class
+============
+
+.. js:class:: Reply
+
+  **context**: action
+
+  This class represents a HTTP response message. It provides some methods to
+  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 details.
+
+.. code-block:: lua
+
+  local reply = txn:reply({status = 400}) -- default HTTP 400 reason-phase used
+  reply:add_header("content-type", "text/html")
+  reply:add_header("cache-control", "no-cache")
+  reply:add_header("cache-control", "no-store")
+  reply:set_body("<html><body><h1>invalid request<h1></body></html>")
+..
+
+  :see: :js:func:`TXN.reply`
+
+.. js:attribute:: Reply.status
+
+  The reply status code. By default, the status code is set to 200.
+
+  :returns: integer
+
+.. js:attribute:: Reply.reason
+
+  The reason string describing the status code.
+
+  :returns: string
+
+.. js:attribute:: Reply.headers
+
+  A table indexing all reply headers by name. To each name is associated an
+  ordered list of values.
+
+  :returns: Lua table
+
+.. code-block:: lua
+
+  {
+    ["content-type"]  = { "text/html" },
+    ["cache-control"] = {"no-cache", "no-store" },
+    x_header_name     = { "value1", "value2", ... }
+    ...
+  }
+..
+
+.. js:attribute:: Reply.body
+
+  The reply payload.
+
+  :returns: string
+
+.. js:function:: Reply.set_status(REPLY, status[, reason])
+
+  Set the reply status code and optionally the reason-phrase. If the reason is
+  not provided, the default reason corresponding to the status code is used.
+
+  :param class_reply reply: The related Reply object.
+  :param integer status: The reply status code.
+  :param string reason: The reply status reason (optional).
+
+.. js:function:: Reply.add_header(REPLY, name, value)
+
+  Add a header to the reply object. If the header does not already exist, a new
+  entry is created with its name as index and a one-element list containing its
+  value as value. Otherwise, the header value is appended to the ordered list of
+  values associated to the header name.
+
+  :param class_reply reply: The related Reply object.
+  :param string name: The header field name.
+  :param string value: The header field value.
+
+.. js:function:: Reply.del_header(REPLY, name)
+
+  Remove all occurrences of a header name from the reply object.
+
+  :param class_reply reply: The related Reply object.
+  :param string name: The header field name.
+
+.. js:function:: Reply.set_body(REPLY, body)
+
+  Set the reply payload.
+
+  :param class_reply reply: The related Reply object.
+  :param string body: The reply payload.
+
+.. _socket_class:
+
+Socket class
+============
+
+.. js:class:: Socket
+
+  This class must be compatible with the Lua Socket class. Only the 'client'
+  functions are available. See the Lua Socket documentation:
+
+  `http://w3.impa.br/~diego/software/luasocket/tcp.html
+  <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
+
+.. js:function:: Socket.close(socket)
+
+  Closes a TCP object. The internal socket used by the object is closed and the
+  local address to which the object was bound is made available to other
+  applications. No further operations (except for further calls to the close
+  method) are allowed on a closed Socket.
+
+  :param class_socket socket: Is the manipulated Socket.
+
+  Note: It is important to close all used sockets once they are not needed,
+  since, in many systems, each socket uses a file descriptor, which are limited
+  system resources. Garbage-collected objects are automatically closed before
+  destruction, though.
+
+.. js:function:: Socket.connect(socket, address[, port])
+
+  Attempts to connect a socket object to a remote host.
+
+
+  In case of error, the method returns nil followed by a string describing the
+  error. In case of success, the method returns 1.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :param string address: can be an IP address or a host name. See below for more
+   information.
+  :param integer port: must be an integer number in the range [1..64K].
+  :returns: 1 or nil.
+
+  An address field extension permits to use the connect() function to connect to
+  other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is
+  the basically expected format. This format requires the port.
+
+  Other format accepted are a socket path like "/socket/path", it permits to
+  connect to a socket. Abstract namespaces are supported with the prefix
+  "abns@", and finally a file descriptor can be passed with the prefix "fd@".
+  The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be
+  passed int the string. The syntax "127.0.0.1:1234" is valid. In this case, the
+  parameter *port* must not be set.
+
+.. js:function:: Socket.connect_ssl(socket, address, port)
+
+  Same behavior than the function socket:connect, but uses SSL.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :returns: 1 or nil.
+
+.. js:function:: Socket.getpeername(socket)
+
+  Returns information about the remote side of a connected client object.
+
+  Returns a string with the IP address of the peer, followed by the port number
+  that peer is using for the connection. In case of error, the method returns
+  nil.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :returns: a string containing the server information.
+
+.. js:function:: Socket.getsockname(socket)
+
+  Returns the local address information associated to the object.
+
+  The method returns a string with local IP address and a number with the port.
+  In case of error, the method returns nil.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :returns: a string containing the client information.
+
+.. js:function:: Socket.receive(socket, [pattern [, prefix]])
+
+  Reads data from a client object, according to the specified read pattern.
+  Patterns follow the Lua file I/O format, and the difference in performance
+  between all patterns is negligible.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :param string|integer pattern: Describe what is required (see below).
+  :param string prefix: A string which will be prefix the returned data.
+  :returns:  a string containing the required data or nil.
+
+  Pattern can be any of the following:
+
+  * **`*a`**: reads from the socket until the connection is closed. No
+              end-of-line translation is performed;
+
+  * **`*l`**: reads a line of text from the Socket. The line is terminated by a
+              LF character (ASCII 10), optionally preceded by a CR character
+              (ASCII 13). The CR and LF characters are not included in the
+              returned line.  In fact, all CR characters are ignored by the
+              pattern. This is the default pattern.
+
+  * **number**: causes the method to read a specified number of bytes from the
+                Socket. Prefix is an optional string to be concatenated to the
+                beginning of any received data before return.
+
+  * **empty**: If the pattern is left empty, the default option is `*l`.
+
+  If successful, the method returns the received pattern. In case of error, the
+  method returns nil followed by an error message which can be the string
+  'closed' in case the connection was closed before the transmission was
+  completed or the string 'timeout' in case there was a timeout during the
+  operation. Also, after the error message, the function returns the partial
+  result of the transmission.
+
+  Important note: This function was changed severely. It used to support
+  multiple patterns (but I have never seen this feature used) and now it
+  doesn't anymore.  Partial results used to be returned in the same way as
+  successful results. This last feature violated the idea that all functions
+  should return nil on error.  Thus it was changed too.
+
+.. js:function:: Socket.send(socket, data [, start [, end ]])
+
+  Sends data through client object.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :param string data: The data that will be sent.
+  :param integer start: The start position in the buffer of the data which will
+   be sent.
+  :param integer end: The end position in the buffer of the data which will
+   be sent.
+  :returns: see below.
+
+  Data is the string to be sent. The optional arguments i and j work exactly
+  like the standard string.sub Lua function to allow the selection of a
+  substring to be sent.
+
+  If successful, the method returns the index of the last byte within [start,
+  end] that has been sent. Notice that, if start is 1 or absent, this is
+  effectively the total number of bytes sent. In case of error, the method
+  returns nil, followed by an error message, followed by the index of the last
+  byte within [start, end] that has been sent. You might want to try again from
+  the byte following that. The error message can be 'closed' in case the
+  connection was closed before the transmission was completed or the string
+  'timeout' in case there was a timeout during the operation.
+
+  Note: Output is not buffered. For small strings, it is always better to
+  concatenate them in Lua (with the '..' operator) and send the result in one
+  call instead of calling the method several times.
+
+.. js:function:: Socket.setoption(socket, option [, value])
+
+  Just implemented for compatibility, this cal does nothing.
+
+.. js:function:: Socket.settimeout(socket, value [, mode])
+
+  Changes the timeout values for the object. All I/O operations are blocking.
+  That is, any call to the methods send, receive, and accept will block
+  indefinitely, until the operation completes. The settimeout method defines a
+  limit on the amount of time the I/O methods can block. When a timeout time
+  has elapsed, the affected methods give up and fail with an error code.
+
+  The amount of time to wait is specified as the value parameter, in seconds.
+
+  The timeout modes are not implemented, the only settable timeout is the
+  inactivity time waiting for complete the internal buffer send or waiting for
+  receive data.
+
+  :param class_socket socket: Is the manipulated Socket.
+  :param float value: The timeout value. Use floating point to specify
+   milliseconds.
+
+.. _regex_class:
+
+Regex class
+===========
+
+.. js:class:: Regex
+
+  This class allows the usage of HAProxy regexes because classic lua doesn't
+  provides regexes. This class inherits the HAProxy compilation options, so the
+  regexes can be libc regex, pcre regex or pcre JIT regex.
+
+  The expression matching number is limited to 20 per regex. The only available
+  option is case sensitive.
+
+  Because regexes compilation is a heavy process, it is better to define all
+  your regexes in the **body context** and use it during the runtime.
+
+.. code-block:: lua
+
+  -- Create the regex
+  st, regex = Regex.new("needle (..) (...)", true);
+
+  -- Check compilation errors
+  if st == false then
+    print "error: " .. regex
+  end
+
+  -- Match the regexes
+  print(regex:exec("Looking for a needle in the haystack")) -- true
+  print(regex:exec("Lokking for a cat in the haystack"))    -- false
+
+  -- Extract words
+  st, list = regex:match("Looking for a needle in the haystack")
+  print(st)      -- true
+  print(list[1]) -- needle in the
+  print(list[2]) -- in
+  print(list[3]) -- the
+
+.. js:function:: Regex.new(regex, case_sensitive)
+
+  Create and compile a regex.
+
+  :param string regex: The regular expression according with the libc or pcre
+   standard
+  :param boolean case_sensitive: Match is case sensitive or not.
+  :returns: boolean status and :ref:`regex_class` or string containing fail
+   reason.
+
+.. js:function:: Regex.exec(regex, str)
+
+  Execute the regex.
+
+  :param class_regex regex: A :ref:`regex_class` object.
+  :param string str: The input string will be compared with the compiled regex.
+  :returns: a boolean status according with the match result.
+
+.. js:function:: Regex.match(regex, str)
+
+  Execute the regex and return matched expressions.
+
+  :param class_map map: A :ref:`regex_class` object.
+  :param string str: The input string will be compared with the compiled regex.
+  :returns: a boolean status according with the match result, and
+   a table containing all the string matched in order of declaration.
+
+.. _map_class:
+
+Map class
+=========
+
+.. js:class:: Map
+
+  This class permits to do some lookups in HAProxy maps. The declared maps can
+  be modified during the runtime through the HAProxy management socket.
+
+.. code-block:: lua
+
+  default = "usa"
+
+  -- 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;
+
+    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);
+
+    if (loc == nil) then
+      return default;
+    end
+
+    return loc;
+  end);
+
+.. js:attribute:: Map._int
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.int` is also available for compatibility.
+
+.. js:attribute:: Map._ip
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.ip` is also available for compatibility.
+
+.. js:attribute:: Map._str
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.str` is also available for compatibility.
+
+.. js:attribute:: Map._beg
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.beg` is also available for compatibility.
+
+.. js:attribute:: Map._sub
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.sub` is also available for compatibility.
+
+.. js:attribute:: Map._dir
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.dir` is also available for compatibility.
+
+.. js:attribute:: Map._dom
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.dom` is also available for compatibility.
+
+.. js:attribute:: Map._end
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+.. js:attribute:: Map._reg
+
+  See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
+  samples" and subchapter "ACL basics" to understand this pattern matching
+  method.
+
+  Note that :js:attr:`Map.reg` is also available for compatibility.
+
+
+.. js:function:: Map.new(file, method)
+
+  Creates and load a map.
+
+  :param string file: Is the file containing the map.
+  :param integer method: Is the map pattern matching method. See the attributes
+   of the Map class.
+  :returns: a class Map object.
+  :see: The Map attributes: :js:attr:`Map._int`, :js:attr:`Map._ip`,
+    :js:attr:`Map._str`, :js:attr:`Map._beg`, :js:attr:`Map._sub`,
+    :js:attr:`Map._dir`, :js:attr:`Map._dom`, :js:attr:`Map._end` and
+    :js:attr:`Map._reg`.
+
+.. js:function:: Map.lookup(map, str)
+
+  Perform a lookup in a map.
+
+  :param class_map map: Is the class Map object.
+  :param string str: Is the string used as key.
+  :returns: a string containing the result or nil if no match.
+
+.. js:function:: Map.slookup(map, str)
+
+  Perform a lookup in a map.
+
+  :param class_map map: Is the class Map object.
+  :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
+
+  This class is used with applets that requires the 'http' mode. The http applet
+  can be registered with the *core.register_service()* function. They are used
+  for processing an http request like a server in back of HAProxy.
+
+  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)
+     applet:add_header("content-length", string.len(response))
+     applet:add_header("content-type", "text/plain")
+     applet:start_response()
+     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 always return 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 fetches related to the HTTP dependent
+  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 always return a string. Note that the applet
+  execution place cannot access to a valid HAProxy core HTTP
+  transaction, so some sample fetches related to the HTTP dependent
+  values (hdr, path, ...) are not available.
+
+.. js:attribute:: AppletHTTP.method
+
+  :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: table
+
+  The attribute headers returns a table 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 table has 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:function:: AppletHTTP.set_status(applet, code [, reason])
+
+  This function sets the HTTP status code for the response. The allowed code are
+  from 100 to 599.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param integer code: the status code returned to the client.
+  :param string reason: the status reason returned to the client (optional).
+
+.. js:function:: AppletHTTP.add_header(applet, name, value)
+
+  This function adds a header in the response. Duplicated headers are not
+  collapsed. The special header *content-length* is used to determinate the
+  response length. If it does not exist, a *transfer-encoding: chunked* is set,
+  and all the write from the function *AppletHTTP:send()* become a chunk.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param string name: the header name
+  :param string value: the header value
+
+.. js:function:: AppletHTTP.start_response(applet)
+
+  This function indicates to the HTTP engine that it can process and send the
+  response headers. After this called we cannot add headers to the response; We
+  cannot use the *AppletHTTP:send()* function if the
+  *AppletHTTP:start_response()* is not called.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+
+.. js:function:: AppletHTTP.getline(applet)
+
+  This function returns a string containing one line from the http body. If the
+  data returned doesn't contains a final '\\n' its assumed than its the last
+  available data before the end of stream.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :returns: a string. The string can be empty if we reach the end of the stream.
+
+.. js:function:: AppletHTTP.receive(applet, [size])
+
+  Reads data from the HTTP body, according to the specified read *size*. If the
+  *size* is missing, the function tries to read all the content of the stream
+  until the end. If the *size* is bigger than the http body, it returns the
+  amount of data available.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param integer size: the required read size.
+  :returns: always return a string,the string can be empty is the connection is
+   closed.
+
+.. js:function:: AppletHTTP.send(applet, msg)
+
+  Send the message *msg* on the http request body.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param string msg: the message to send.
+
+.. js:function:: AppletHTTP.get_priv(applet)
+
+  Return Lua data stored in the current transaction. If no data are stored,
+  it returns a nil value.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :returns: the opaque data previously stored, or nil if nothing is
+   available.
+  :see: :js:func:`AppletHTTP.set_priv`
+
+.. js:function:: AppletHTTP.set_priv(applet, data)
+
+  Store any data in the current HAProxy transaction. This action replaces the
+  old stored data.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param opaque data: The data which is stored in the transaction.
+  :see: :js:func:`AppletHTTP.get_priv`
+
+.. js:function:: AppletHTTP.set_var(applet, var, value[, ifexist])
+
+  Converts a Lua type in a HAProxy type and store it in a variable <var>.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :param type value: The value associated to the variable. The type ca be string
+   or integer.
+  :param boolean ifexist: If this parameter is set to true the variable will
+   only be set if it was defined elsewhere (i.e. used within the configuration).
+   For global variables (using the "proc" scope), they will only be updated and
+   never created. It is highly recommended to always set this to true.
+
+  :see: :js:func:`AppletHTTP.unset_var`
+  :see: :js:func:`AppletHTTP.get_var`
+
+.. js:function:: AppletHTTP.unset_var(applet, var)
+
+  Unset the variable <var>.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :see: :js:func:`AppletHTTP.set_var`
+  :see: :js:func:`AppletHTTP.get_var`
+
+.. js:function:: AppletHTTP.get_var(applet, var)
+
+  Returns data stored in the variable <var> converter in Lua type.
+
+  :param class_AppletHTTP applet: An :ref:`applethttp_class`
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :see: :js:func:`AppletHTTP.set_var`
+  :see: :js:func:`AppletHTTP.unset_var`
+
+.. _applettcp_class:
+
+AppletTCP class
+===============
+
+.. js:class:: AppletTCP
+
+  This class is used with applets that requires the 'tcp' mode. The tcp applet
+  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 always return 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(applet)
+
+  This function returns a string containing one line from the stream. If the
+  data returned doesn't contains a final '\\n' its assumed than its the last
+  available data before the end of stream.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :returns: a string. The string can be empty if we reach the end of the stream.
+
+.. js:function:: AppletTCP.receive(applet, [size])
+
+  Reads data from the TCP stream, according to the specified read *size*. If the
+  *size* is missing, the function tries to read all the content of the stream
+  until the end.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :param integer size: the required read size.
+  :returns: always return a string, the string can be empty if the connection is
+   closed.
+
+.. js:function:: AppletTCP.send(appletmsg)
+
+  Send the message on the stream.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :param string msg: the message to send.
+
+.. js:function:: AppletTCP.get_priv(applet)
+
+  Return Lua data stored in the current transaction. If no data are stored,
+  it returns a nil value.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :returns: the opaque data previously stored, or nil if nothing is
+   available.
+  :see: :js:func:`AppletTCP.set_priv`
+
+.. js:function:: AppletTCP.set_priv(applet, data)
+
+  Store any data in the current HAProxy transaction. This action replaces the
+  old stored data.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :param opaque data: The data which is stored in the transaction.
+  :see: :js:func:`AppletTCP.get_priv`
+
+.. js:function:: AppletTCP.set_var(applet, var, value[, ifexist])
+
+  Converts a Lua type in a HAProxy type and stores it in a variable <var>.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :param type value: The value associated to the variable. The type can be
+   string or integer.
+  :param boolean ifexist: If this parameter is set to true the variable will
+   only be set if it was defined elsewhere (i.e. used within the configuration).
+   For global variables (using the "proc" scope), they will only be updated and
+   never created. It is highly recommended to always set this to true.
+
+  :see: :js:func:`AppletTCP.unset_var`
+  :see: :js:func:`AppletTCP.get_var`
+
+.. js:function:: AppletTCP.unset_var(applet, var)
+
+  Unsets the variable <var>.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :see: :js:func:`AppletTCP.unset_var`
+  :see: :js:func:`AppletTCP.set_var`
+
+.. js:function:: AppletTCP.get_var(applet, var)
+
+  Returns data stored in the variable <var> converter in Lua type.
+
+  :param class_AppletTCP applet: An :ref:`applettcp_class`
+  :param string var: The variable name according with the HAProxy variable
+   syntax.
+  :see: :js:func:`AppletTCP.unset_var`
+  :see: :js:func:`AppletTCP.set_var`
+
+.. _sticktable_class:
+
+StickTable class
+================
+
+.. js:class:: StickTable
+
+  **context**: task, action, sample-fetch
+
+  This class can be used to access the HAProxy stick tables from Lua.
+
+.. js:function:: StickTable.info()
+
+  Returns stick table attributes as a Lua table. See HAProxy documentation for
+  "stick-table" for canonical info, or check out example below.
+
+  :returns: Lua table
+
+  Assume our table has IPv4 key and gpc0 and conn_rate "columns":
+
+.. code-block:: lua
+
+  {
+    expire=<int>,  # Value in ms
+    size=<int>,    # Maximum table size
+    used=<int>,    # Actual number of entries in table
+    data={         # Data columns, with types as key, and periods as values
+                     (-1 if type is not rate counter)
+      conn_rate=<int>,
+      gpc0=-1
+    },
+    length=<int>,  # max string length for string table keys, key length
+                   # otherwise
+    nopurge=<boolean>, # purge oldest entries when table is full
+    type="ip"      # can be "ip", "ipv6", "integer", "string", "binary"
+  }
+
+.. js:function:: StickTable.lookup(key)
+
+   Returns stick table entry for given <key>
+
+   :param string key: Stick table key (IP addresses and strings are supported)
+   :returns: Lua table
+
+.. js:function:: StickTable.dump([filter])
+
+   Returns all entries in stick table. An optional filter can be used
+   to extract entries with specific data values. Filter is a table with valid
+   comparison operators as keys followed by data type name and value pairs.
+   Check out the HAProxy docs for "show table" for more details. For the
+   reference, the supported operators are:
+
+     "eq", "ne", "le", "lt", "ge", "gt"
+
+   For large tables, execution of this function can take a long time (for
+   HAProxy standards). That's also true when filter is used, so take care and
+   measure the impact.
+
+   :param table filter: Stick table filter
+   :returns: Stick table entries (table)
+
+   See below for example filter, which contains 4 entries (or comparisons).
+   (Maximum number of filter entries is 4, defined in the source code)
+
+.. code-block:: lua
+
+    local filter = {
+      {"gpc0", "gt", 30}, {"gpc1", "gt", 20}}, {"conn_rate", "le", 10}
+    }
+
+.. _action_class:
+
+Action class
+=============
+
+.. js:class:: Act
+
+  **context**: action
+
+  This class contains all return codes an action may return. It is the lua
+  equivalent to HAProxy "ACT_RET_*" code.
+
+.. code-block:: lua
+
+  core.register_action("deny", { "http-req" }, function (txn)
+      return act.DENY
+   end)
+..
+.. js:attribute:: act.CONTINUE
+
+  This attribute is an integer (0). It instructs HAProxy to continue the
+  current ruleset processing on the message. It is the default return code
+  for a lua action.
+
+  :returns: integer
+
+.. js:attribute:: act.STOP
+
+  This attribute is an integer (1). It instructs HAProxy to stop the current
+  ruleset processing on the message.
+
+.. js:attribute:: act.YIELD
+
+  This attribute is an integer (2). It instructs HAProxy to temporarily pause
+  the message processing. It will be resumed later on the same rule. The
+  corresponding lua script is re-executed for the start.
+
+.. js:attribute:: act.ERROR
+
+  This attribute is an integer (3). It triggers an internal errors The message
+  processing is stopped and the transaction is terminated. For HTTP streams, an
+  HTTP 500 error is returned to the client.
+
+  :returns: integer
+
+.. js:attribute:: act.DONE
+
+  This attribute is an integer (4). It instructs HAProxy to stop the message
+  processing.
+
+  :returns: integer
+
+.. js:attribute:: act.DENY
+
+  This attribute is an integer (5). It denies the current message. The message
+  processing is stopped and the transaction is terminated. For HTTP streams, an
+  HTTP 403 error is returned to the client if the deny is returned during the
+  request analysis. During the response analysis, a HTTP 502 error is returned
+  and the server response is discarded.
+
+  :returns: integer
+
+.. js:attribute:: act.ABORT
+
+  This attribute is an integer (6). It aborts the current message. The message
+  processing is stopped and the transaction is terminated. For HTTP streams,
+  HAProxy assumes a response was already sent to the client. From the Lua
+  actions point of view, when this code is used, the transaction is terminated
+  with no reply.
+
+  :returns: integer
+
+.. js:attribute:: act.INVALID
+
+  This attribute is an integer (7). It triggers an internal errors. The message
+  processing is stopped and the transaction is terminated. For HTTP streams, an
+  HTTP 400 error is returned to the client if the error is returned during the
+  request analysis. During the response analysis, a HTTP 502 error is returned
+  and the server response is discarded.
+
+  :returns: integer
+
+.. js:function:: act:wake_time(milliseconds)
+
+  **context**: action
+
+  Set the script pause timeout to the specified time, defined in
+  milliseconds.
+
+  :param integer milliseconds: the required milliseconds.
+
+  This function may be used when a lua action returns `act.YIELD`, to force its
+  wake-up at most after the specified number of milliseconds.
+
+.. _filter_class:
+
+Filter class
+=============
+
+.. js:class:: filter
+
+  **context**: filter
+
+  This class contains return codes some filter callback functions may return. It
+  also contains configuration flags and some helper functions. To understand how
+  the filter API works, see `doc/internal/filters.txt` documentation.
+
+.. js:attribute:: filter.CONTINUE
+
+  This attribute is an integer (1). It may be returned by some filter callback
+  functions to instruct this filtering step is finished for this filter.
+
+.. js:attribute:: filter.WAIT
+
+  This attribute is an integer (0). It may be returned by some filter callback
+  functions to instruct the filtering must be paused, waiting for more data or
+  for an external event depending on this filter.
+
+.. js:attribute:: filter.ERROR
+
+  This attribute is an integer (-1). It may be returned by some filter callback
+  functions to trigger an error.
+
+.. js:attribute:: filter.FLT_CFG_FL_HTX
+
+  This attribute is a flag corresponding to the filter flag FLT_CFG_FL_HTX. When
+  it is set for a filter, it means the filter is able to filter HTTP streams.
+
+.. js:function:: filter.register_data_filter(chn)
+
+  **context**: filter
+
+  Enable the data filtering on the channel **chn** for the current filter. It
+  may be called at any time from any callback functions proceeding the data
+  analysis.
+
+  :param class_Channel chn: A :ref:`channel_class`.
+
+.. js:function:: filter.unregister_data_filter(chn)
+
+  **context**: filter
+
+  Disable the data filtering on the channel **chn** for the current filter. It
+  may be called at any time from any callback functions.
+
+  :param class_Channel chn: A :ref:`channel_class`.
+
+.. js:function:: filter.wake_time(milliseconds)
+
+  **context**: filter
+
+  Set the script pause timeout to the specified time, defined in
+  milliseconds.
+
+  :param integer milliseconds: the required milliseconds.
+
+  This function may be used from any lua filter callback function to force its
+  wake-up at most after the specified number of milliseconds. Especially, when
+  `filter.CONTINUE` is returned.
+
+
+A filters is declared using :js:func:`core.register_filter()` function. The
+provided class will be used to instantiate filters. It may define following
+attributes:
+
+* id: The filter identifier. It is a string that identifies the filter and is
+      optional.
+
+* flags: The filter flags. Only :js:attr:`filter.FLT_CFG_FL_HTX` may be set
+         for now.
+
+Such filter class must also define all required callback functions in the
+following list. Note that :js:func:`Filter.new()` must be defined otherwise the
+filter is ignored. Others are optional.
+
+* .. js:function:: FILTER.new()
+
+  Called to instantiate a new filter. This function must be defined.
+
+  :returns: a Lua object that will be used as filter instance for the current
+            stream.
+
+* .. js:function:: FILTER.start_analyze(flt, txn, chn)
+
+  Called when the analysis starts on the channel **chn**.
+
+* .. js:function:: FILTER.end_analyze(flt, txn, chn)
+
+  Called when the analysis ends on the channel **chn**.
+
+* .. js:function:: FILTER.http_headers(flt, txn, http_msg)
+
+  Called just before the HTTP payload analysis and after any processing on the
+  HTTP message **http_msg**. This callback functions is only called for HTTP
+  streams.
+
+* .. js:function:: FILTER.http_payload(flt, txn, http_msg)
+
+  Called during the HTTP payload analysis on the HTTP message **http_msg**. This
+  callback functions is only called for HTTP streams.
+
+* .. js:function:: FILTER.http_end(flt, txn, http_msg)
+
+  Called after the HTTP payload analysis on the HTTP message **http_msg**. This
+  callback functions is only called for HTTP streams.
+
+* .. js:function:: FILTER.tcp_payload(flt, txn, chn)
+
+  Called during the TCP payload analysis on the channel **chn**.
+
+Here is a full example:
+
+.. code-block:: lua
+
+  Trace = {}
+  Trace.id = "Lua trace filter"
+  Trace.flags = filter.FLT_CFG_FL_HTX;
+  Trace.__index = Trace
+
+  function Trace:new()
+      local trace = {}
+      setmetatable(trace, Trace)
+      trace.req_len = 0
+      trace.res_len = 0
+      return trace
+  end
+
+  function Trace:start_analyze(txn, chn)
+      if chn:is_resp() then
+          print("Start response analysis")
+      else
+          print("Start request analysis")
+      end
+      filter.register_data_filter(self, chn)
+  end
+
+  function Trace:end_analyze(txn, chn)
+      if chn:is_resp() then
+          print("End response analysis: "..self.res_len.." bytes filtered")
+      else
+          print("End request analysis: "..self.req_len.." bytes filtered")
+      end
+  end
+
+  function Trace:http_headers(txn, http_msg)
+      stline  = http_msg:get_stline()
+      if http_msg.channel:is_resp() then
+          print("response:")
+          print(stline.version.." "..stline.code.." "..stline.reason)
+      else
+          print("request:")
+          print(stline.method.." "..stline.uri.." "..stline.version)
+      end
+
+      for n, hdrs in pairs(http_msg:get_headers()) do
+          for i,v in pairs(hdrs) do
+              print(n..": "..v)
+          end
+      end
+      return filter.CONTINUE
+  end
+
+  function Trace:http_payload(txn, http_msg)
+      body = http_msg:body(-20000)
+      if http_msg.channel:is_resp() then
+          self.res_len = self.res_len + body:len()
+      else
+          self.req_len = self.req_len + body:len()
+      end
+  end
+
+  core.register_filter("trace", Trace, function(trace, args)
+      return trace
+  end)
+
+..
+
+.. _httpmessage_class:
+
+HTTPMessage class
+===================
+
+.. js:class:: HTTPMessage
+
+  **context**: filter
+
+  This class contains all functions to manipulate a HTTP message. For now, this
+  class is only available from a filter context.
+
+.. js:function:: HTTPMessage.add_header(http_msg, name, value)
+
+  Appends a HTTP header field in the HTTP message **http_msg** whose name is
+  specified in **name** and whose value is defined in **value**.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string name: The header name.
+  :param string value: The header value.
+
+.. js:function:: HTTPMessage.append(http_msg, string)
+
+  This function copies the string **string** at the end of incoming data of the
+  HTTP message **http_msg**. The function returns the copied length on success
+  or -1 if data cannot be copied.
+
+  Same that :js:func:`HTTPMessage.insert(http_msg, string, http_msg:input())`.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string string: The data to copy at the end of incoming data.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: HTTPMessage.body(http_msgl[, offset[, length]])
+
+  This function returns **length** bytes of incoming data from the HTTP message
+  **http_msg**, starting at the offset **offset**. The data are not removed from
+  the buffer.
+
+  By default, if no length is provided, all incoming data found, starting at the
+  given offset, are returned. If **length** is set to -1, the function tries to
+  retrieve a maximum of data. Because it is called in the filter context, it
+  never yield. Not providing an offset is the same as setting it to 0. A
+  positive offset is relative to the beginning of incoming data of the
+  http_message buffer while negative offset is relative to their end.
+
+  If there is no incoming data and the HTTP message can't receive more data,
+  a 'nil' value is returned.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param integer offset: *optional* The offset in incoming data to start to get
+   data. 0 by default. May be negative to be relative to the end of incoming
+   data.
+  :param integer length: *optional* The expected length of data to retrieve.
+   All incoming data by default. May be set to -1 to get a maximum of data.
+  :returns: a string containing the data found or nil.
+
+.. js:function:: HTTPMessage.eom(http_msg)
+
+  This function returns true if the end of message is reached for the HTTP
+  message **http_msg**.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :returns: an integer containing the amount of available bytes.
+
+.. js:function:: HTTPMessage.del_header(http_msg, name)
+
+  Removes all HTTP header fields in the HTTP message **http_msg** whose name is
+  specified in **name**.
+
+  :param class_httpmessage http_msg: The manipulated http message.
+  :param string name: The header name.
+
+.. js:function:: HTTPMessage.get_headers(http_msg)
+
+  Returns a table containing all the headers of the HTTP message **http_msg**.
+
+  :param class_httpmessage http_msg: The manipulated http message.
+  :returns: table of headers.
+
+  This is the form of the returned table:
+
+.. code-block:: lua
+
+  http_msg:get_headers()['<header-name>'][<header-index>] = "<header-value>"
+
+  local hdr = http_msg: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:: HTTPMessage.get_stline(http_msg)
+
+  Returns a table containing the start-line of the HTTP message **http_msg**.
+
+  :param class_httpmessage http_msg: The manipulated http message.
+  :returns: the start-line.
+
+  This is the form of the returned table:
+
+.. code-block:: lua
+
+  -- for the request :
+  {"method" = string, "uri" = string, "version" = string}
+
+  -- for the response:
+  {"version" = string, "code" = string, "reason" = string}
+..
+
+.. js:function:: HTTPMessage.forward(http_msg, length)
+
+  This function forwards **length** bytes of data from the HTTP message
+  **http_msg**. Because it is called in the filter context, it never yields. Only
+  available incoming data may be forwarded, event if the requested length
+  exceeds the available amount of incoming data. It returns the amount of data
+  forwarded.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param integer int: The amount of data to forward.
+
+.. js:function:: HTTPMessage.input(http_msg)
+
+  This function returns the length of incoming data in the HTTP message
+  **http_msg** from the filter point of view.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :returns: an integer containing the amount of available bytes.
+
+.. js:function:: HTTPMessage.insert(http_msg, string[, offset])
+
+  This function copies the string **string** at the offset **offset** in
+  incoming data of the HTTP message **http_msg**. The function returns the
+  copied length on success or -1 if data cannot be copied.
+
+  By default, if no offset is provided, the string is copied in front of
+  incoming data. A positive offset is relative to the beginning of incoming data
+  of the HTTP message while negative offset is relative to their end.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string string: The data to copy into incoming data.
+  :param integer offset: *optional* The offset in incoming data where to copy
+   data. 0 by default. May be negative to be relative to the end of incoming
+   data.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: HTTPMessage.is_full(http_msg)
+
+  This function returns true if the HTTP message **http_msg** is full.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :returns: a boolean
+
+.. js:function:: HTTPMessage.is_resp(http_msg)
+
+  This function returns true if the HTTP message **http_msg** is the response
+  one.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :returns: a boolean
+
+.. js:function:: HTTPMessage.may_recv(http_msg)
+
+  This function returns true if the HTTP message **http_msg** may still receive
+  data.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :returns: a boolean
+
+.. js:function:: HTTPMessage.output(http_msg)
+
+  This function returns the length of outgoing data of the HTTP message
+  **http_msg**.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :returns: an integer containing the amount of available bytes.
+
+.. js:function:: HTTPMessage.prepend(http_msg, string)
+
+  This function copies the string **string** in front of incoming data of the
+  HTTP message **http_msg**. The function returns the copied length on success
+  or -1 if data cannot be copied.
+
+  Same that :js:func:`HTTPMessage.insert(http_msg, string, 0)`.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string string: The data to copy in front of incoming data.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: HTTPMessage.remove(http_msg[, offset[, length]])
+
+  This function removes **length** bytes of incoming data of the HTTP message
+  **http_msg**, starting at offset **offset**. This function returns number of
+  bytes removed on success.
+
+  By default, if no length is provided, all incoming data, starting at the given
+  offset, are removed. Not providing an offset is the same that setting it
+  to 0. A positive offset is relative to the beginning of incoming data of the
+  HTTP message while negative offset is relative to the end.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param integer offset: *optional* The offset in incoming data where to start
+   to remove data. 0 by default. May be negative to be relative to the end of
+   incoming data.
+  :param integer length: *optional* The length of data to remove. All incoming
+   data by default.
+  :returns: an integer containing the amount of bytes removed.
+
+.. js:function:: HTTPMessage.rep_header(http_msg, name, regex, replace)
+
+  Matches the regular expression in all occurrences of header field **name**
+  according to regex **regex**, and replaces them with the string **replace**.
+  The replacement value can contain back references like \1, \2, ... This
+  function acts on whole header lines, regardless of the number of values they
+  may contain.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string name: The header name.
+  :param string regex: The match regular expression.
+  :param string replace: The replacement value.
+
+.. js:function:: HTTPMessage.rep_value(http_msg, name, regex, replace)
+
+  Matches the regular expression on every comma-delimited value of header field
+  **name** according to regex **regex**, and replaces them with the string
+  **replace**.  The replacement value can contain back references like \1, \2,
+  ...
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string name: The header name.
+  :param string regex: The match regular expression.
+  :param string replace: The replacement value.
+
+.. js:function:: HTTPMessage.send(http_msg, string)
+
+  This function requires immediate send of the string **string**. It means the
+  string is copied at the beginning of incoming data of the HTTP message
+  **http_msg** and immediately forwarded. Because it is called in the filter
+  context, it never yields.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string string: The data to send.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: HTTPMessage.set(http_msg, string[, offset[, length]])
+
+  This function replaces **length** bytes of incoming data of the HTTP message
+  **http_msg**, starting at offset **offset**, by the string **string**. The
+  function returns the copied length on success or -1 if data cannot be copied.
+
+  By default, if no length is provided, all incoming data, starting at the given
+  offset, are replaced. Not providing an offset is the same as setting it
+  to 0. A positive offset is relative to the beginning of incoming data of the
+  HTTP message while negative offset is relative to the end.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string string: The data to copy into incoming data.
+  :param integer offset: *optional* The offset in incoming data where to start
+   the data replacement. 0 by default. May be negative to be relative to the
+   end of incoming data.
+  :param integer length: *optional* The length of data to replace. All incoming
+   data by default.
+  :returns: an integer containing the amount of bytes copied or -1.
+
+.. js:function:: HTTPMessage.set_eom(http_msg)
+
+  This function set the end of message for the HTTP message **http_msg**.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+
+.. js:function:: HTTPMessage.set_header(http_msg, name, value)
+
+  This variable replace all occurrence of all header matching the name **name**,
+  by only one containing the value **value**.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string name: The header name.
+  :param string value: The header value.
+
+  This function does the same work as the following code:
+
+.. code-block:: lua
+
+      http_msg:del_header("header")
+      http_msg:add_header("header", "value")
+..
+
+.. js:function:: HTTPMessage.set_method(http_msg, method)
+
+  Rewrites the request method with the string **method**. The HTTP message
+  **http_msg** must be the request.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string method: The new method.
+
+.. js:function:: HTTPMessage.set_path(http_msg, path)
+
+  Rewrites the request path with the string **path**. The HTTP message
+  **http_msg** must be the request.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string method: The new method.
+
+.. js:function:: HTTPMessage.set_query(http_msg, query)
+
+  Rewrites the request's query string which appears after the first question
+  mark ("?") with the string **query**. The HTTP message **http_msg** must be
+  the request.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string query: The new query.
+
+.. js:function:: HTTPMessage.set_status(http_msg, status[, reason])
+
+  Rewrites the response status code with the integer **code** and optional the
+  reason **reason**. If no custom reason is provided, it will be generated from
+  the status. The HTTP message **http_msg** must be the response.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param integer status: The new response status code.
+  :param string reason: The new response reason (optional).
+
+.. js:function:: HTTPMessage.set_uri(http_msg, uri)
+
+  Rewrites the request URI with the string **uri**. The HTTP message
+  **http_msg** must be the request.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+  :param string uri: The new uri.
+
+.. js:function:: HTTPMessage.unset_eom(http_msg)
+
+  This function remove the end of message for the HTTP message **http_msg**.
+
+  :param class_httpmessage http_msg: The manipulated HTTP message.
+
+.. _CertCache_class:
+
+CertCache class
+================
+
+.. js:class:: CertCache
+
+   This class allows to update an SSL certificate file in the memory of the
+   current HAProxy process. It will do the same as "set ssl cert" + "commit ssl
+   cert" over the HAProxy CLI.
+
+.. js:function:: CertCache.set(certificate)
+
+  This function updates a certificate in memory.
+
+  :param table certificate: A table containing the fields to update.
+  :param string certificate.filename: The mandatory filename of the certificate
+   to update, it must already exist in memory.
+  :param string certificate.crt: A certificate in the PEM format. It can also
+   contain a private key.
+  :param string certificate.key: A private key in the PEM format.
+  :param string certificate.ocsp: An OCSP response in base64. (cf management.txt)
+  :param string certificate.issuer: The certificate of the OCSP issuer.
+  :param string certificate.sctl: An SCTL file.
+
+.. code-block:: lua
+
+    CertCache.set{filename="certs/localhost9994.pem.rsa", crt=crt}
+
+
+External Lua libraries
+======================
+
+A lot of useful lua libraries can be found here:
+
+* Lua toolbox has been superseded by
+  `https://luarocks.org/ <https://luarocks.org/>`_
+
+  The old lua toolbox source code is still available here
+  `https://github.com/catwell/lua-toolbox <https://github.com/catwell/lua-toolbox>`_ (DEPRECATED)
+
+Redis client library:
+
+* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
+
+This is an example about the usage of the Redis library within HAProxy.
+Note that each call to any function of this library can throw an error if
+the socket connection fails.
+
+.. code-block:: lua
+
+    -- load the redis library
+    local redis = require("redis");
+
+    function do_something(txn)
+
+       -- create and connect new tcp socket
+       local tcp = core.tcp();
+       tcp:settimeout(1);
+       tcp:connect("127.0.0.1", 6379);
+
+       -- use the redis library with this new socket
+       local client = redis.connect({socket=tcp});
+       client:ping();
+
+    end
+
+OpenSSL:
+
+* `http://mkottman.github.io/luacrypto/index.html
+  <http://mkottman.github.io/luacrypto/index.html>`_
+
+* `https://github.com/brunoos/luasec/wiki
+  <https://github.com/brunoos/luasec/wiki>`_