blob: f3e5cb786b88b91f66fbe1eccf4a2009cfed950a [file] [log] [blame]
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001.. toctree::
2 :maxdepth: 2
3
4
5How Lua runs in HAProxy
6=======================
7
8HAProxy Lua running contexts
9----------------------------
10
11The Lua code executed in HAProxy can be processed in 2 main modes. The first one
12is the **initialisation mode**, and the second is the **runtime mode**.
13
14* In the **initialisation mode**, we can perform DNS solves, but we cannot
15 perform socket I/O. In this initialisation mode, HAProxy still blocked during
16 the execution of the Lua program.
17
18* In the **runtime mode**, we cannot perform DNS solves, but we can use sockets.
19 The execution of the Lua code is multiplexed with the requests processing, so
20 the Lua code seems to be run in blocking, but it is not the case.
21
22The Lua code is loaded in one or more files. These files contains main code and
23functions. Lua have 6 execution context.
24
251. The Lua file **body context**. It is executed during the load of the Lua file
26 in the HAProxy `[global]` section with the directive `lua-load`. It is
27 executed in initialisation mode. This section is use for configuring Lua
28 bindings in HAProxy.
29
David Carlier61fdf8b2015-10-02 11:59:38 +0100302. The Lua **init context**. It is a Lua function executed just after the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010031 HAProxy configuration parsing. The execution is in initialisation mode. In
32 this context the HAProxy environment are already initialized. It is useful to
33 check configuration, or initializing socket connections or tasks. These
34 functions are declared in the body context with the Lua function
35 `core.register_init()`. The prototype of the function is a simple function
36 without return value and without parameters, like this: `function fcn()`.
37
David Carlier61fdf8b2015-10-02 11:59:38 +0100383. The Lua **task context**. It is a Lua function executed after the start
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010039 of the HAProxy scheduler, and just after the declaration of the task with the
40 Lua function `core.register_task()`. This context can be concurrent with the
41 traffic processing. It is executed in runtime mode. The prototype of the
42 function is a simple function without return value and without parameters,
43 like this: `function fcn()`.
44
David Carlier61fdf8b2015-10-02 11:59:38 +0100454. The **action context**. It is a Lua function conditionally executed. These
Thierry FOURNIERa2d02252015-10-01 15:00:42 +020046 actions are registered by the Lua directives "`core.register_action()`". The
47 prototype of the Lua called function is a function with doesn't returns
48 anything and that take an object of class TXN as entry. `function fcn(txn)`.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010049
505. The **sample-fetch context**. This function takes a TXN object as entry
51 argument and returns a string. These types of function cannot execute any
52 blocking function. They are useful to aggregate some of original HAProxy
53 sample-fetches and return the result. The prototype of the function is
54 `function string fcn(txn)`. These functions can be registered with the Lua
55 function `core.register_fetches()`. Each declared sample-fetch is prefixed by
56 the string "lua.".
57
58 **NOTE**: It is possible that this function cannot found the required data
59 in the original HAProxy sample-fetches, in this case, it cannot return the
60 result. This case is not yet supported
61
David Carlier61fdf8b2015-10-02 11:59:38 +0100626. The **converter context**. It is a Lua function that takes a string as input
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010063 and returns another string as output. These types of function are stateless,
64 it cannot access to any context. They don't execute any blocking function.
65 The call prototype is `function string fcn(string)`. This function can be
66 registered with the Lua function `core.register_converters()`. Each declared
67 converter is prefixed by the string "lua.".
68
69HAProxy Lua Hello world
70-----------------------
71
72HAProxy configuration file (`hello_world.conf`):
73
74::
75
76 global
77 lua-load hello_world.lua
78
79 listen proxy
80 bind 127.0.0.1:10001
Thierry FOURNIERa2d02252015-10-01 15:00:42 +020081 tcp-request inspect-delay 1s
82 tcp-request content use-service lua.hello_world
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010083
84HAProxy Lua file (`hello_world.lua`):
85
86.. code-block:: lua
87
Thierry FOURNIERa2d02252015-10-01 15:00:42 +020088 core.register_service("hello_world", "tcp", function(applet)
89 applet:send("hello world\n")
90 end)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010091
92How to start HAProxy for testing this configuration:
93
94::
95
96 ./haproxy -f hello_world.conf
97
98On other terminal, you can test with telnet:
99
100::
101
102 #:~ telnet 127.0.0.1 10001
103 hello world
104
105Core class
106==========
107
108.. js:class:: core
109
110 The "core" class contains all the HAProxy core functions. These function are
111 useful for the controlling the execution flow, registering hooks, manipulating
112 global maps or ACL, ...
113
114 "core" class is basically provided with HAProxy. No `require` line is
115 required to uses these function.
116
David Carlier61fdf8b2015-10-02 11:59:38 +0100117 The "core" class is static, it is not possible to create a new object of this
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100118 type.
119
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100120.. js:attribute:: core.emerg
121
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100122 :returns: integer
123
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100124 This attribute is an integer, it contains the value of the loglevel "emergency" (0).
125
126.. js:attribute:: core.alert
127
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100128 :returns: integer
129
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100130 This attribute is an integer, it contains the value of the loglevel "alert" (1).
131
132.. js:attribute:: core.crit
133
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100134 :returns: integer
135
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100136 This attribute is an integer, it contains the value of the loglevel "critical" (2).
137
138.. js:attribute:: core.err
139
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100140 :returns: integer
141
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100142 This attribute is an integer, it contains the value of the loglevel "error" (3).
143
144.. js:attribute:: core.warning
145
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100146 :returns: integer
147
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100148 This attribute is an integer, it contains the value of the loglevel "warning" (4).
149
150.. js:attribute:: core.notice
151
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100152 :returns: integer
153
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100154 This attribute is an integer, it contains the value of the loglevel "notice" (5).
155
156.. js:attribute:: core.info
157
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100158 :returns: integer
159
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100160 This attribute is an integer, it contains the value of the loglevel "info" (6).
161
162.. js:attribute:: core.debug
163
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100164 :returns: integer
165
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100166 This attribute is an integer, it contains the value of the loglevel "debug" (7).
167
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100168.. js:attribute:: core.proxies
169
170 **context**: task, action, sample-fetch, converter
171
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400172 This attribute is a table of declared proxies (frontend and backends). Each
173 proxy give an access to his list of listeners and servers. The table is
174 indexed by proxy name, and each entry is of type :ref:`proxy_class`.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100175
Thierry FOURNIER9b82a582017-07-24 13:30:43 +0200176 Warning, if you are declared frontend and backend with the same name, only one
177 of these are listed.
178
179 :see: :js:attr:`core.backends`
180 :see: :js:attr:`core.frontends`
181
182.. js:attribute:: core.backends
183
184 **context**: task, action, sample-fetch, converter
185
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400186 This attribute is a table of declared proxies with backend capability. Each
187 proxy give an access to his list of listeners and servers. The table is
188 indexed by the backend name, and each entry is of type :ref:`proxy_class`.
Thierry FOURNIER9b82a582017-07-24 13:30:43 +0200189
190 :see: :js:attr:`core.proxies`
191 :see: :js:attr:`core.frontends`
192
193.. js:attribute:: core.frontends
194
195 **context**: task, action, sample-fetch, converter
196
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400197 This attribute is a table of declared proxies with frontend capability. Each
198 proxy give an access to his list of listeners and servers. The table is
199 indexed by the frontend name, and each entry is of type :ref:`proxy_class`.
Thierry FOURNIER9b82a582017-07-24 13:30:43 +0200200
201 :see: :js:attr:`core.proxies`
202 :see: :js:attr:`core.backends`
203
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100204.. js:function:: core.log(loglevel, msg)
205
206 **context**: body, init, task, action, sample-fetch, converter
207
David Carlier61fdf8b2015-10-02 11:59:38 +0100208 This function sends a log. The log is sent, according with the HAProxy
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100209 configuration file, on the default syslog server if it is configured and on
210 the stderr if it is allowed.
211
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100212 :param integer loglevel: Is the log level associated with the message. It is a
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100213 number between 0 and 7.
214 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100215 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
216 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
217 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
218 :see: :js:func:`core.Debug`
219 :see: :js:func:`core.Info`
220 :see: :js:func:`core.Warning`
221 :see: :js:func:`core.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100222
223.. js:function:: core.Debug(msg)
224
225 **context**: body, init, task, action, sample-fetch, converter
226
227 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100228 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100229
230 Does the same job than:
231
232.. code-block:: lua
233
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100234 function Debug(msg)
235 core.log(core.debug, msg)
236 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100237..
238
239.. js:function:: core.Info(msg)
240
241 **context**: body, init, task, action, sample-fetch, converter
242
243 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100244 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100245
246.. code-block:: lua
247
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100248 function Info(msg)
249 core.log(core.info, msg)
250 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100251..
252
253.. js:function:: core.Warning(msg)
254
255 **context**: body, init, task, action, sample-fetch, converter
256
257 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100258 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100259
260.. code-block:: lua
261
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100262 function Warning(msg)
263 core.log(core.warning, msg)
264 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100265..
266
267.. js:function:: core.Alert(msg)
268
269 **context**: body, init, task, action, sample-fetch, converter
270
271 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100272 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100273
274.. code-block:: lua
275
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100276 function Alert(msg)
277 core.log(core.alert, msg)
278 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100279..
280
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100281.. js:function:: core.add_acl(filename, key)
282
283 **context**: init, task, action, sample-fetch, converter
284
285 Add the ACL *key* in the ACLs list referenced by the file *filename*.
286
287 :param string filename: the filename that reference the ACL entries.
288 :param string key: the key which will be added.
289
290.. js:function:: core.del_acl(filename, key)
291
292 **context**: init, task, action, sample-fetch, converter
293
294 Delete the ACL entry referenced by the key *key* in the list of ACLs
295 referenced by *filename*.
296
297 :param string filename: the filename that reference the ACL entries.
298 :param string key: the key which will be deleted.
299
300.. js:function:: core.del_map(filename, key)
301
302 **context**: init, task, action, sample-fetch, converter
303
304 Delete the map entry indexed with the specified key in the list of maps
305 referenced by his filename.
306
307 :param string filename: the filename that reference the map entries.
308 :param string key: the key which will be deleted.
309
Thierry Fourniereea77c02016-03-18 08:47:13 +0100310.. js:function:: core.get_info()
311
312 **context**: body, init, task, action, sample-fetch, converter
313
Ilya Shipitsin2075ca82020-03-06 23:22:22 +0500314 Returns HAProxy core information. We can found information like the uptime,
Thierry Fourniereea77c02016-03-18 08:47:13 +0100315 the pid, memory pool usage, tasks number, ...
316
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100317 These information are also returned by the management socket via the command
318 "show info". See the management socket documentation for more information
Thierry Fourniereea77c02016-03-18 08:47:13 +0100319 about the content of these variables.
320
321 :returns: an array of values.
322
Thierry Fournierb1f46562016-01-21 09:46:15 +0100323.. js:function:: core.now()
324
325 **context**: body, init, task, action
326
327 This function returns the current time. The time returned is fixed by the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100328 HAProxy core and assures than the hour will be monotonic and that the system
Thierry Fournierb1f46562016-01-21 09:46:15 +0100329 call 'gettimeofday' will not be called too. The time is refreshed between each
330 Lua execution or resume, so two consecutive call to the function "now" will
331 probably returns the same result.
332
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400333 :returns: a table which contains two entries "sec" and "usec". "sec"
Thierry Fournierb1f46562016-01-21 09:46:15 +0100334 contains the current at the epoch format, and "usec" contains the
335 current microseconds.
336
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100337.. js:function:: core.http_date(date)
338
339 **context**: body, init, task, action
340
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100341 This function take a string representing http date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100342 containing the corresponding date with a epoch format. A valid http date
343 me respect the format IMF, RFC850 or ASCTIME.
344
345 :param string date: a date http-date formatted
346 :returns: integer containing epoch date
347 :see: :js:func:`core.imf_date`.
348 :see: :js:func:`core.rfc850_date`.
349 :see: :js:func:`core.asctime_date`.
350 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
351
352.. js:function:: core.imf_date(date)
353
354 **context**: body, init, task, action
355
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100356 This function take a string representing IMF date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100357 containing the corresponding date with a epoch format.
358
359 :param string date: a date IMF formatted
360 :returns: integer containing epoch date
361 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
362
363 The IMF format is like this:
364
365.. code-block:: text
366
367 Sun, 06 Nov 1994 08:49:37 GMT
368..
369
370.. js:function:: core.rfc850_date(date)
371
372 **context**: body, init, task, action
373
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100374 This function take a string representing RFC850 date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100375 containing the corresponding date with a epoch format.
376
377 :param string date: a date RFC859 formatted
378 :returns: integer containing epoch date
379 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
380
381 The RFC850 format is like this:
382
383.. code-block:: text
384
385 Sunday, 06-Nov-94 08:49:37 GMT
386..
387
388.. js:function:: core.asctime_date(date)
389
390 **context**: body, init, task, action
391
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100392 This function take a string representing ASCTIME date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100393 containing the corresponding date with a epoch format.
394
395 :param string date: a date ASCTIME formatted
396 :returns: integer containing epoch date
397 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
398
399 The ASCTIME format is like this:
400
401.. code-block:: text
402
403 Sun Nov 6 08:49:37 1994
404..
405
406.. js:function:: core.rfc850_date(date)
407
408 **context**: body, init, task, action
409
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100410 This function take a string representing http date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100411 containing the corresponding date with a epoch format.
412
413 :param string date: a date http-date formatted
414
415.. js:function:: core.asctime_date(date)
416
417 **context**: body, init, task, action
418
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100419 This function take a string representing http date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100420 containing the corresponding date with a epoch format.
421
422 :param string date: a date http-date formatted
423
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100424.. js:function:: core.msleep(milliseconds)
425
426 **context**: body, init, task, action
427
428 The `core.msleep()` stops the Lua execution between specified milliseconds.
429
430 :param integer milliseconds: the required milliseconds.
431
Thierry Fournierf61aa632016-02-19 20:56:00 +0100432.. js:attribute:: core.proxies
433
434 **context**: body, init, task, action, sample-fetch, converter
435
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100436 Proxies is a table containing the list of all proxies declared in the
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400437 configuration file. The table is indexed by the proxy name, and each entry
438 of the proxies table is an object of type :ref:`proxy_class`.
439
440 Warning, if you have declared a frontend and backend with the same name, only
441 one of these are listed.
Thierry Fournierf61aa632016-02-19 20:56:00 +0100442
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100443.. js:function:: core.register_action(name, actions, func [, nb_args])
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200444
445 **context**: body
446
David Carlier61fdf8b2015-10-02 11:59:38 +0100447 Register a Lua function executed as action. All the registered action can be
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200448 used in HAProxy with the prefix "lua.". An action gets a TXN object class as
449 input.
450
451 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200452 :param table actions: is a table of string describing the HAProxy actions who
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200453 want to register to. The expected actions are 'tcp-req',
454 'tcp-res', 'http-req' or 'http-res'.
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100455 :param integer nb_args: is the expected number of argument for the action.
456 By default the value is 0.
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200457 :param function func: is the Lua function called to work as converter.
458
459 The prototype of the Lua function used as argument is:
460
461.. code-block:: lua
462
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100463 function(txn [, arg1 [, arg2]])
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200464..
465
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100466 * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200467 current request or TCP stream.
468
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100469 * **argX**: this is argument provided through the HAProxy configuration file.
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100470
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100471 Here, an example of action registration. The action just send an 'Hello world'
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200472 in the logs.
473
474.. code-block:: lua
475
476 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
477 txn:Info("Hello world")
478 end)
479..
480
481 This example code is used in HAproxy configuration like this:
482
483::
484
485 frontend tcp_frt
486 mode tcp
487 tcp-request content lua.hello-world
488
489 frontend http_frt
490 mode http
491 http-request lua.hello-world
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100492..
493
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100494 A second example using arguments
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100495
496.. code-block:: lua
497
498 function hello_world(txn, arg)
499 txn:Info("Hello world for " .. arg)
500 end
501 core.register_action("hello-world", { "tcp-req", "http-req" }, hello_world, 2)
502..
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200503
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100504 This example code is used in HAproxy configuration like this:
505
506::
507
508 frontend tcp_frt
509 mode tcp
510 tcp-request content lua.hello-world everybody
511..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100512.. js:function:: core.register_converters(name, func)
513
514 **context**: body
515
David Carlier61fdf8b2015-10-02 11:59:38 +0100516 Register a Lua function executed as converter. All the registered converters
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100517 can be used in HAProxy with the prefix "lua.". An converter get a string as
518 input and return a string as output. The registered function can take up to 9
519 values as parameter. All the value are strings.
520
521 :param string name: is the name of the converter.
522 :param function func: is the Lua function called to work as converter.
523
524 The prototype of the Lua function used as argument is:
525
526.. code-block:: lua
527
528 function(str, [p1 [, p2 [, ... [, p5]]]])
529..
530
531 * **str** (*string*): this is the input value automatically converted in
532 string.
533 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100534 the HAProxy configuration file. The number of arguments doesn't exceed 5.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100535 The order and the nature of these is conventionally choose by the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100536 developer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100537
538.. js:function:: core.register_fetches(name, func)
539
540 **context**: body
541
David Carlier61fdf8b2015-10-02 11:59:38 +0100542 Register a Lua function executed as sample fetch. All the registered sample
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100543 fetch can be used in HAProxy with the prefix "lua.". A Lua sample fetch
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100544 return a string as output. The registered function can take up to 9 values as
545 parameter. All the value are strings.
546
547 :param string name: is the name of the converter.
548 :param function func: is the Lua function called to work as sample fetch.
549
550 The prototype of the Lua function used as argument is:
551
552.. code-block:: lua
553
554 string function(txn, [p1 [, p2 [, ... [, p5]]]])
555..
556
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100557 * **txn** (:ref:`txn_class`): this is the txn object associated with the current
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100558 request.
559 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100560 the HAProxy configuration file. The number of arguments doesn't exceed 5.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100561 The order and the nature of these is conventionally choose by the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100562 developer.
563 * **Returns**: A string containing some data, or nil if the value cannot be
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100564 returned now.
565
566 lua example code:
567
568.. code-block:: lua
569
570 core.register_fetches("hello", function(txn)
571 return "hello"
572 end)
573..
574
575 HAProxy example configuration:
576
577::
578
579 frontend example
580 http-request redirect location /%[lua.hello]
581
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200582.. js:function:: core.register_service(name, mode, func)
583
584 **context**: body
585
David Carlier61fdf8b2015-10-02 11:59:38 +0100586 Register a Lua function executed as a service. All the registered service can
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200587 be used in HAProxy with the prefix "lua.". A service gets an object class as
588 input according with the required mode.
589
590 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200591 :param string mode: is string describing the required mode. Only 'tcp' or
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200592 'http' are allowed.
593 :param function func: is the Lua function called to work as converter.
594
595 The prototype of the Lua function used as argument is:
596
597.. code-block:: lua
598
599 function(applet)
600..
601
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100602 * **applet** *applet* will be a :ref:`applettcp_class` or a
603 :ref:`applethttp_class`. It depends the type of registered applet. An applet
604 registered with the 'http' value for the *mode* parameter will gets a
605 :ref:`applethttp_class`. If the *mode* value is 'tcp', the applet will gets
606 a :ref:`applettcp_class`.
607
608 **warning**: Applets of type 'http' cannot be called from 'tcp-*'
609 rulesets. Only the 'http-*' rulesets are authorized, this means
610 that is not possible to call an HTTP applet from a proxy in tcp
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100611 mode. Applets of type 'tcp' can be called from anywhere.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200612
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100613 Here, an example of service registration. The service just send an 'Hello world'
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200614 as an http response.
615
616.. code-block:: lua
617
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100618 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200619 local response = "Hello World !"
620 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200621 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200622 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200623 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200624 applet:send(response)
625 end)
626..
627
628 This example code is used in HAproxy configuration like this:
629
630::
631
632 frontend example
633 http-request use-service lua.hello-world
634
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100635.. js:function:: core.register_init(func)
636
637 **context**: body
638
639 Register a function executed after the configuration parsing. This is useful
640 to check any parameters.
641
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100642 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100643
644 The prototype of the Lua function used as argument is:
645
646.. code-block:: lua
647
648 function()
649..
650
651 It takes no input, and no output is expected.
652
653.. js:function:: core.register_task(func)
654
655 **context**: body, init, task, action, sample-fetch, converter
656
657 Register and start independent task. The task is started when the HAProxy
658 main scheduler starts. For example this type of tasks can be executed to
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100659 perform complex health checks.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100660
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100661 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100662
663 The prototype of the Lua function used as argument is:
664
665.. code-block:: lua
666
667 function()
668..
669
670 It takes no input, and no output is expected.
671
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100672.. js:function:: core.register_cli([path], usage, func)
673
674 **context**: body
675
676 Register and start independent task. The task is started when the HAProxy
677 main scheduler starts. For example this type of tasks can be executed to
678 perform complex health checks.
679
680 :param array path: is the sequence of word for which the cli execute the Lua
681 binding.
682 :param string usage: is the usage message displayed in the help.
683 :param function func: is the Lua function called to handle the CLI commands.
684
685 The prototype of the Lua function used as argument is:
686
687.. code-block:: lua
688
689 function(AppletTCP, [arg1, [arg2, [...]]])
690..
691
692 I/O are managed with the :ref:`applettcp_class` object. Args are given as
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100693 parameter. The args embed the registered path. If the path is declared like
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100694 this:
695
696.. code-block:: lua
697
698 core.register_cli({"show", "ssl", "stats"}, "Display SSL stats..", function(applet, arg1, arg2, arg3, arg4, arg5)
699 end)
700..
701
702 And we execute this in the prompt:
703
704.. code-block:: text
705
706 > prompt
707 > show ssl stats all
708..
709
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100710 Then, arg1, arg2 and arg3 will contains respectively "show", "ssl" and "stats".
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100711 arg4 will contain "all". arg5 contains nil.
712
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100713.. js:function:: core.set_nice(nice)
714
715 **context**: task, action, sample-fetch, converter
716
717 Change the nice of the current task or current session.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100718
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100719 :param integer nice: the nice value, it must be between -1024 and 1024.
720
721.. js:function:: core.set_map(filename, key, value)
722
723 **context**: init, task, action, sample-fetch, converter
724
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100725 Set the value *value* associated to the key *key* in the map referenced by
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100726 *filename*.
727
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100728 :param string filename: the Map reference
729 :param string key: the key to set or replace
730 :param string value: the associated value
731
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100732.. js:function:: core.sleep(int seconds)
733
734 **context**: body, init, task, action
735
736 The `core.sleep()` functions stop the Lua execution between specified seconds.
737
738 :param integer seconds: the required seconds.
739
740.. js:function:: core.tcp()
741
742 **context**: init, task, action
743
744 This function returns a new object of a *socket* class.
745
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100746 :returns: A :ref:`socket_class` object.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100747
Thierry Fournier1de16592016-01-27 09:49:07 +0100748.. js:function:: core.concat()
749
750 **context**: body, init, task, action, sample-fetch, converter
751
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100752 This function returns a new concat object.
Thierry Fournier1de16592016-01-27 09:49:07 +0100753
754 :returns: A :ref:`concat_class` object.
755
Thierry FOURNIER0a99b892015-08-26 00:14:17 +0200756.. js:function:: core.done(data)
757
758 **context**: body, init, task, action, sample-fetch, converter
759
760 :param any data: Return some data for the caller. It is useful with
761 sample-fetches and sample-converters.
762
763 Immediately stops the current Lua execution and returns to the caller which
764 may be a sample fetch, a converter or an action and returns the specified
765 value (ignored for actions). It is used when the LUA process finishes its
766 work and wants to give back the control to HAProxy without executing the
767 remaining code. It can be seen as a multi-level "return".
768
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100769.. js:function:: core.yield()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100770
771 **context**: task, action, sample-fetch, converter
772
773 Give back the hand at the HAProxy scheduler. It is used when the LUA
774 processing consumes a lot of processing time.
775
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100776.. js:function:: core.parse_addr(address)
777
778 **context**: body, init, task, action, sample-fetch, converter
779
780 :param network: is a string describing an ipv4 or ipv6 address and optionally
781 its network length, like this: "127.0.0.1/8" or "aaaa::1234/32".
782 :returns: a userdata containing network or nil if an error occurs.
783
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100784 Parse ipv4 or ipv6 addresses and its facultative associated network.
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100785
786.. js:function:: core.match_addr(addr1, addr2)
787
788 **context**: body, init, task, action, sample-fetch, converter
789
790 :param addr1: is an address created with "core.parse_addr".
791 :param addr2: is an address created with "core.parse_addr".
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100792 :returns: boolean, true if the network of the addresses match, else returns
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100793 false.
794
Ilya Shipitsin2075ca82020-03-06 23:22:22 +0500795 Match two networks. For example "127.0.0.1/32" matches "127.0.0.0/8". The order
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100796 of network is not important.
797
Thierry FOURNIER / OZON.IO8a1027a2016-11-24 20:48:38 +0100798.. js:function:: core.tokenize(str, separators [, noblank])
799
800 **context**: body, init, task, action, sample-fetch, converter
801
802 This function is useful for tokenizing an entry, or splitting some messages.
803 :param string str: The string which will be split.
804 :param string separators: A string containing a list of separators.
805 :param boolean noblank: Ignore empty entries.
806 :returns: an array of string.
807
808 For example:
809
810.. code-block:: lua
811
812 local array = core.tokenize("This function is useful, for tokenizing an entry.", "., ", true)
813 print_r(array)
814..
815
816 Returns this array:
817
818.. code-block:: text
819
820 (table) table: 0x21c01e0 [
821 1: (string) "This"
822 2: (string) "function"
823 3: (string) "is"
824 4: (string) "useful"
825 5: (string) "for"
826 6: (string) "tokenizing"
827 7: (string) "an"
828 8: (string) "entry"
829 ]
830..
831
Thierry Fournierf61aa632016-02-19 20:56:00 +0100832.. _proxy_class:
833
834Proxy class
835============
836
837.. js:class:: Proxy
838
839 This class provides a way for manipulating proxy and retrieving information
840 like statistics.
841
Thierry FOURNIER817e7592017-07-24 14:35:04 +0200842.. js:attribute:: Proxy.name
843
844 Contain the name of the proxy.
845
Baptiste Assmann46c72552017-10-26 21:51:58 +0200846.. js:attribute:: Proxy.uuid
847
848 Contain the unique identifier of the proxy.
849
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100850.. js:attribute:: Proxy.servers
851
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400852 Contain a table with the attached servers. The table is indexed by server
853 name, and each server entry is an object of type :ref:`server_class`.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100854
Adis Nezirovic8878f8e2018-07-13 12:18:33 +0200855.. js:attribute:: Proxy.stktable
856
857 Contains a stick table object attached to the proxy.
858
Thierry Fournierff480422016-02-25 08:36:46 +0100859.. js:attribute:: Proxy.listeners
860
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400861 Contain a table with the attached listeners. The table is indexed by listener
862 name, and each each listeners entry is an object of type
863 :ref:`listener_class`.
Thierry Fournierff480422016-02-25 08:36:46 +0100864
Thierry Fournierf61aa632016-02-19 20:56:00 +0100865.. js:function:: Proxy.pause(px)
866
867 Pause the proxy. See the management socket documentation for more information.
868
869 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
870 proxy.
871
872.. js:function:: Proxy.resume(px)
873
874 Resume the proxy. See the management socket documentation for more
875 information.
876
877 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
878 proxy.
879
880.. js:function:: Proxy.stop(px)
881
882 Stop the proxy. See the management socket documentation for more information.
883
884 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
885 proxy.
886
887.. js:function:: Proxy.shut_bcksess(px)
888
889 Kill the session attached to a backup server. See the management socket
890 documentation for more information.
891
892 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
893 proxy.
894
895.. js:function:: Proxy.get_cap(px)
896
897 Returns a string describing the capabilities of the proxy.
898
899 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
900 proxy.
901 :returns: a string "frontend", "backend", "proxy" or "ruleset".
902
903.. js:function:: Proxy.get_mode(px)
904
905 Returns a string describing the mode of the current proxy.
906
907 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
908 proxy.
909 :returns: a string "tcp", "http", "health" or "unknown"
910
911.. js:function:: Proxy.get_stats(px)
912
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100913 Returns a table containing the proxy statistics. The statistics returned are
Thierry Fournierf61aa632016-02-19 20:56:00 +0100914 not the same if the proxy is frontend or a backend.
915
916 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
917 proxy.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400918 :returns: a key/value table containing stats
Thierry Fournierf61aa632016-02-19 20:56:00 +0100919
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100920.. _server_class:
921
922Server class
923============
924
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400925.. js:class:: Server
926
927 This class provides a way for manipulating servers and retrieving information.
928
Patrick Hemmera62ae7e2018-04-29 14:23:48 -0400929.. js:attribute:: Server.name
930
931 Contain the name of the server.
932
933.. js:attribute:: Server.puid
934
935 Contain the proxy unique identifier of the server.
936
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100937.. js:function:: Server.is_draining(sv)
938
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400939 Return true if the server is currently draining sticky connections.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100940
941 :param class_server sv: A :ref:`server_class` which indicates the manipulated
942 server.
943 :returns: a boolean
944
Patrick Hemmer32d539f2018-04-29 14:25:46 -0400945.. js:function:: Server.set_maxconn(sv, weight)
946
947 Dynamically change the maximum connections of the server. See the management
948 socket documentation for more information about the format of the string.
949
950 :param class_server sv: A :ref:`server_class` which indicates the manipulated
951 server.
952 :param string maxconn: A string describing the server maximum connections.
953
954.. js:function:: Server.get_maxconn(sv, weight)
955
956 This function returns an integer representing the server maximum connections.
957
958 :param class_server sv: A :ref:`server_class` which indicates the manipulated
959 server.
960 :returns: an integer.
961
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100962.. js:function:: Server.set_weight(sv, weight)
963
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400964 Dynamically change the weight of the server. See the management socket
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100965 documentation for more information about the format of the string.
966
967 :param class_server sv: A :ref:`server_class` which indicates the manipulated
968 server.
969 :param string weight: A string describing the server weight.
970
971.. js:function:: Server.get_weight(sv)
972
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400973 This function returns an integer representing the server weight.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100974
975 :param class_server sv: A :ref:`server_class` which indicates the manipulated
976 server.
977 :returns: an integer.
978
Joseph C. Sible49bbf522020-05-04 22:20:32 -0400979.. js:function:: Server.set_addr(sv, addr[, port])
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100980
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400981 Dynamically change the address of the server. See the management socket
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100982 documentation for more information about the format of the string.
983
984 :param class_server sv: A :ref:`server_class` which indicates the manipulated
985 server.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400986 :param string addr: A string describing the server address.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100987
988.. js:function:: Server.get_addr(sv)
989
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400990 Returns a string describing the address of the server.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100991
992 :param class_server sv: A :ref:`server_class` which indicates the manipulated
993 server.
994 :returns: A string
995
996.. js:function:: Server.get_stats(sv)
997
998 Returns server statistics.
999
1000 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1001 server.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001002 :returns: a key/value table containing stats
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +01001003
1004.. js:function:: Server.shut_sess(sv)
1005
1006 Shutdown all the sessions attached to the server. See the management socket
1007 documentation for more information about this function.
1008
1009 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1010 server.
1011
1012.. js:function:: Server.set_drain(sv)
1013
1014 Drain sticky sessions. See the management socket documentation for more
1015 information about this function.
1016
1017 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1018 server.
1019
1020.. js:function:: Server.set_maint(sv)
1021
1022 Set maintenance mode. See the management socket documentation for more
1023 information about this function.
1024
1025 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1026 server.
1027
1028.. js:function:: Server.set_ready(sv)
1029
1030 Set normal mode. See the management socket documentation for more information
1031 about this function.
1032
1033 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1034 server.
1035
1036.. js:function:: Server.check_enable(sv)
1037
1038 Enable health checks. See the management socket documentation for more
1039 information about this function.
1040
1041 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1042 server.
1043
1044.. js:function:: Server.check_disable(sv)
1045
1046 Disable health checks. See the management socket documentation for more
1047 information about this function.
1048
1049 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1050 server.
1051
1052.. js:function:: Server.check_force_up(sv)
1053
1054 Force health-check up. See the management socket documentation for more
1055 information about this function.
1056
1057 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1058 server.
1059
1060.. js:function:: Server.check_force_nolb(sv)
1061
1062 Force health-check nolb mode. See the management socket documentation for more
1063 information about this function.
1064
1065 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1066 server.
1067
1068.. js:function:: Server.check_force_down(sv)
1069
1070 Force health-check down. See the management socket documentation for more
1071 information about this function.
1072
1073 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1074 server.
1075
1076.. js:function:: Server.agent_enable(sv)
1077
1078 Enable agent check. See the management socket documentation for more
1079 information about this function.
1080
1081 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1082 server.
1083
1084.. js:function:: Server.agent_disable(sv)
1085
1086 Disable agent check. See the management socket documentation for more
1087 information about this function.
1088
1089 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1090 server.
1091
1092.. js:function:: Server.agent_force_up(sv)
1093
1094 Force agent check up. See the management socket documentation for more
1095 information about this function.
1096
1097 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1098 server.
1099
1100.. js:function:: Server.agent_force_down(sv)
1101
1102 Force agent check down. See the management socket documentation for more
1103 information about this function.
1104
1105 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1106 server.
1107
Thierry Fournierff480422016-02-25 08:36:46 +01001108.. _listener_class:
1109
1110Listener class
1111==============
1112
1113.. js:function:: Listener.get_stats(ls)
1114
1115 Returns server statistics.
1116
1117 :param class_listener ls: A :ref:`listener_class` which indicates the
1118 manipulated listener.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001119 :returns: a key/value table containing stats
Thierry Fournierff480422016-02-25 08:36:46 +01001120
Thierry Fournier1de16592016-01-27 09:49:07 +01001121.. _concat_class:
1122
1123Concat class
1124============
1125
1126.. js:class:: Concat
1127
1128 This class provides a fast way for string concatenation. The way using native
1129 Lua concatenation like the code below is slow for some reasons.
1130
1131.. code-block:: lua
1132
1133 str = "string1"
1134 str = str .. ", string2"
1135 str = str .. ", string3"
1136..
1137
1138 For each concatenation, Lua:
1139 * allocate memory for the result,
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001140 * catenate the two string copying the strings in the new memory block,
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001141 * free the old memory block containing the string which is no longer used.
Thierry Fournier1de16592016-01-27 09:49:07 +01001142 This process does many memory move, allocation and free. In addition, the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001143 memory is not really freed, it is just mark mark as unused and wait for the
Thierry Fournier1de16592016-01-27 09:49:07 +01001144 garbage collector.
1145
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001146 The Concat class provide an alternative way to concatenate strings. It uses
Thierry Fournier1de16592016-01-27 09:49:07 +01001147 the internal Lua mechanism (it does not allocate memory), but it doesn't copy
1148 the data more than once.
1149
1150 On my computer, the following loops spends 0.2s for the Concat method and
1151 18.5s for the pure Lua implementation. So, the Concat class is about 1000x
1152 faster than the embedded solution.
1153
1154.. code-block:: lua
1155
1156 for j = 1, 100 do
1157 c = core.concat()
1158 for i = 1, 20000 do
1159 c:add("#####")
1160 end
1161 end
1162..
1163
1164.. code-block:: lua
1165
1166 for j = 1, 100 do
1167 c = ""
1168 for i = 1, 20000 do
1169 c = c .. "#####"
1170 end
1171 end
1172..
1173
1174.. js:function:: Concat.add(concat, string)
1175
1176 This function adds a string to the current concatenated string.
1177
1178 :param class_concat concat: A :ref:`concat_class` which contains the currently
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001179 built string.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001180 :param string string: A new string to concatenate to the current built
Thierry Fournier1de16592016-01-27 09:49:07 +01001181 string.
1182
1183.. js:function:: Concat.dump(concat)
1184
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001185 This function returns the concatenated string.
Thierry Fournier1de16592016-01-27 09:49:07 +01001186
1187 :param class_concat concat: A :ref:`concat_class` which contains the currently
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001188 built string.
Thierry Fournier1de16592016-01-27 09:49:07 +01001189 :returns: the concatenated string
1190
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001191.. _fetches_class:
1192
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001193Fetches class
1194=============
1195
1196.. js:class:: Fetches
1197
1198 This class contains a lot of internal HAProxy sample fetches. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001199 HAProxy "configuration.txt" documentation for more information about her
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001200 usage. They are the chapters 7.3.2 to 7.3.6.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001201
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001202 **warning** some sample fetches are not available in some context. These
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001203 limitations are specified in this documentation when they're useful.
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001204
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001205 :see: :js:attr:`TXN.f`
1206 :see: :js:attr:`TXN.sf`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001207
1208 Fetches are useful for:
1209
1210 * get system time,
1211 * get environment variable,
1212 * get random numbers,
1213 * known backend status like the number of users in queue or the number of
1214 connections established,
1215 * client information like ip source or destination,
1216 * deal with stick tables,
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001217 * Established SSL information,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001218 * HTTP information like headers or method.
1219
1220.. code-block:: lua
1221
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001222 function action(txn)
1223 -- Get source IP
1224 local clientip = txn.f:src()
1225 end
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001226..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001227
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001228.. _converters_class:
1229
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001230Converters class
1231================
1232
1233.. js:class:: Converters
1234
1235 This class contains a lot of internal HAProxy sample converters. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001236 HAProxy documentation "configuration.txt" for more information about her
1237 usage. Its the chapter 7.3.1.
1238
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001239 :see: :js:attr:`TXN.c`
1240 :see: :js:attr:`TXN.sc`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001241
1242 Converters provides statefull transformation. They are useful for:
1243
1244 * converting input to base64,
1245 * applying hash on input string (djb2, crc32, sdbm, wt6),
1246 * format date,
1247 * json escape,
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001248 * extracting preferred language comparing two lists,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001249 * turn to lower or upper chars,
1250 * deal with stick tables.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001251
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001252.. _channel_class:
1253
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001254Channel class
1255=============
1256
1257.. js:class:: Channel
1258
1259 HAProxy uses two buffers for the processing of the requests. The first one is
1260 used with the request data (from the client to the server) and the second is
1261 used for the response data (from the server to the client).
1262
1263 Each buffer contains two types of data. The first type is the incoming data
1264 waiting for a processing. The second part is the outgoing data already
1265 processed. Usually, the incoming data is processed, after it is tagged as
1266 outgoing data, and finally it is sent. The following functions provides tools
1267 for manipulating these data in a buffer.
1268
1269 The following diagram shows where the channel class function are applied.
1270
1271 **Warning**: It is not possible to read from the response in request action,
1272 and it is not possible to read for the request channel in response action.
1273
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001274.. image:: _static/channel.png
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001275
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001276.. js:function:: Channel.dup(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001277
1278 This function returns a string that contain the entire buffer. The data is
1279 not remove from the buffer and can be reprocessed later.
1280
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001281 If the buffer can't receive more data, a 'nil' value is returned.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001282
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001283 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001284 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001285
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001286.. js:function:: Channel.get(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001287
1288 This function returns a string that contain the entire buffer. The data is
1289 consumed from the buffer.
1290
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001291 If the buffer can't receive more data, a 'nil' value is returned.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001292
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001293 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001294 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001295
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001296.. js:function:: Channel.getline(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001297
1298 This function returns a string that contain the first line of the buffer. The
1299 data is consumed. If the data returned doesn't contains a final '\n' its
1300 assumed than its the last available data in the buffer.
1301
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001302 If the buffer can't receive more data, a 'nil' value is returned.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001303
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001304 :param class_channel channel: The manipulated Channel.
Pieter Baauw386a1272015-08-16 15:26:24 +02001305 :returns: a string containing the available line or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001306
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001307.. js:function:: Channel.set(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001308
1309 This function replace the content of the buffer by the string. The function
1310 returns the copied length, otherwise, it returns -1.
1311
1312 The data set with this function are not send. They wait for the end of
1313 HAProxy processing, so the buffer can be full.
1314
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001315 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001316 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001317 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001318
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001319.. js:function:: Channel.append(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001320
1321 This function append the string argument to the content of the buffer. The
1322 function returns the copied length, otherwise, it returns -1.
1323
1324 The data set with this function are not send. They wait for the end of
1325 HAProxy processing, so the buffer can be full.
1326
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001327 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001328 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001329 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001330
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001331.. js:function:: Channel.send(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001332
1333 This function required immediate send of the data. Unless if the connection
1334 is close, the buffer is regularly flushed and all the string can be sent.
1335
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001336 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001337 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001338 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001339
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001340.. js:function:: Channel.get_in_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001341
1342 This function returns the length of the input part of the buffer.
1343
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001344 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001345 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001346
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001347.. js:function:: Channel.get_out_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001348
1349 This function returns the length of the output part of the buffer.
1350
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001351 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001352 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001353
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001354.. js:function:: Channel.forward(channel, int)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001355
1356 This function transfer bytes from the input part of the buffer to the output
1357 part.
1358
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001359 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001360 :param integer int: The amount of data which will be forwarded.
1361
Thierry FOURNIER / OZON.IO65192f32016-11-07 15:28:40 +01001362.. js:function:: Channel.is_full(channel)
1363
1364 This function returns true if the buffer channel is full.
1365
1366 :returns: a boolean
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001367
1368.. _http_class:
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001369
1370HTTP class
1371==========
1372
1373.. js:class:: HTTP
1374
1375 This class contain all the HTTP manipulation functions.
1376
Pieter Baauw386a1272015-08-16 15:26:24 +02001377.. js:function:: HTTP.req_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001378
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001379 Returns a table containing all the request headers.
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001380
1381 :param class_http http: The related http object.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001382 :returns: table of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001383 :see: :js:func:`HTTP.res_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001384
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001385 This is the form of the returned table:
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001386
1387.. code-block:: lua
1388
1389 HTTP:req_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1390
1391 local hdr = HTTP:req_get_headers()
1392 hdr["host"][0] = "www.test.com"
1393 hdr["accept"][0] = "audio/basic q=1"
1394 hdr["accept"][1] = "audio/*, q=0.2"
1395 hdr["accept"][2] = "*/*, q=0.1"
1396..
1397
Pieter Baauw386a1272015-08-16 15:26:24 +02001398.. js:function:: HTTP.res_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001399
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001400 Returns a table containing all the response headers.
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001401
1402 :param class_http http: The related http object.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001403 :returns: table of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001404 :see: :js:func:`HTTP.req_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001405
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001406 This is the form of the returned table:
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001407
1408.. code-block:: lua
1409
1410 HTTP:res_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1411
1412 local hdr = HTTP:req_get_headers()
1413 hdr["host"][0] = "www.test.com"
1414 hdr["accept"][0] = "audio/basic q=1"
1415 hdr["accept"][1] = "audio/*, q=0.2"
1416 hdr["accept"][2] = "*.*, q=0.1"
1417..
1418
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001419.. js:function:: HTTP.req_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001420
1421 Appends an HTTP header field in the request whose name is
1422 specified in "name" and whose value is defined in "value".
1423
1424 :param class_http http: The related http object.
1425 :param string name: The header name.
1426 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001427 :see: :js:func:`HTTP.res_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001428
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001429.. js:function:: HTTP.res_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001430
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001431 Appends an HTTP header field in the response whose name is
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001432 specified in "name" and whose value is defined in "value".
1433
1434 :param class_http http: The related http object.
1435 :param string name: The header name.
1436 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001437 :see: :js:func:`HTTP.req_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001438
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001439.. js:function:: HTTP.req_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001440
1441 Removes all HTTP header fields in the request whose name is
1442 specified in "name".
1443
1444 :param class_http http: The related http object.
1445 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001446 :see: :js:func:`HTTP.res_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001447
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001448.. js:function:: HTTP.res_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001449
1450 Removes all HTTP header fields in the response whose name is
1451 specified in "name".
1452
1453 :param class_http http: The related http object.
1454 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001455 :see: :js:func:`HTTP.req_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001456
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001457.. js:function:: HTTP.req_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001458
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001459 This variable replace all occurrence of all header "name", by only
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001460 one containing the "value".
1461
1462 :param class_http http: The related http object.
1463 :param string name: The header name.
1464 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001465 :see: :js:func:`HTTP.res_set_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001466
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001467 This function does the same work as the following code:
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001468
1469.. code-block:: lua
1470
1471 function fcn(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001472 TXN.http:req_del_header("header")
1473 TXN.http:req_add_header("header", "value")
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001474 end
1475..
1476
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001477.. js:function:: HTTP.res_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001478
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001479 This variable replace all occurrence of all header "name", by only
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001480 one containing the "value".
1481
1482 :param class_http http: The related http object.
1483 :param string name: The header name.
1484 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001485 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001486
Pieter Baauw386a1272015-08-16 15:26:24 +02001487.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001488
1489 Matches the regular expression in all occurrences of header field "name"
1490 according to "regex", and replaces them with the "replace" argument. The
1491 replacement value can contain back references like \1, \2, ... This
1492 function works with the request.
1493
1494 :param class_http http: The related http object.
1495 :param string name: The header name.
1496 :param string regex: The match regular expression.
1497 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001498 :see: :js:func:`HTTP.res_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001499
Pieter Baauw386a1272015-08-16 15:26:24 +02001500.. js:function:: HTTP.res_rep_header(http, name, regex, string)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001501
1502 Matches the regular expression in all occurrences of header field "name"
1503 according to "regex", and replaces them with the "replace" argument. The
1504 replacement value can contain back references like \1, \2, ... This
1505 function works with the request.
1506
1507 :param class_http http: The related http object.
1508 :param string name: The header name.
1509 :param string regex: The match regular expression.
1510 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001511 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001512
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001513.. js:function:: HTTP.req_set_method(http, method)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001514
1515 Rewrites the request method with the parameter "method".
1516
1517 :param class_http http: The related http object.
1518 :param string method: The new method.
1519
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001520.. js:function:: HTTP.req_set_path(http, path)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001521
1522 Rewrites the request path with the "path" parameter.
1523
1524 :param class_http http: The related http object.
1525 :param string path: The new path.
1526
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001527.. js:function:: HTTP.req_set_query(http, query)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001528
1529 Rewrites the request's query string which appears after the first question
1530 mark ("?") with the parameter "query".
1531
1532 :param class_http http: The related http object.
1533 :param string query: The new query.
1534
Thierry FOURNIER0d79cf62015-08-26 14:20:58 +02001535.. js:function:: HTTP.req_set_uri(http, uri)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001536
1537 Rewrites the request URI with the parameter "uri".
1538
1539 :param class_http http: The related http object.
1540 :param string uri: The new uri.
1541
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001542.. js:function:: HTTP.res_set_status(http, status [, reason])
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001543
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001544 Rewrites the response status code with the parameter "code".
1545
1546 If no custom reason is provided, it will be generated from the status.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001547
1548 :param class_http http: The related http object.
1549 :param integer status: The new response status code.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001550 :param string reason: The new response reason (optional).
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001551
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001552.. _txn_class:
1553
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001554TXN class
1555=========
1556
1557.. js:class:: TXN
1558
1559 The txn class contain all the functions relative to the http or tcp
1560 transaction (Note than a tcp stream is the same than a tcp transaction, but
1561 an HTTP transaction is not the same than a tcp stream).
1562
1563 The usage of this class permits to retrieve data from the requests, alter it
1564 and forward it.
1565
1566 All the functions provided by this class are available in the context
1567 **sample-fetches** and **actions**.
1568
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001569.. js:attribute:: TXN.c
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001570
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001571 :returns: An :ref:`converters_class`.
1572
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001573 This attribute contains a Converters class object.
1574
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001575.. js:attribute:: TXN.sc
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001576
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001577 :returns: An :ref:`converters_class`.
1578
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001579 This attribute contains a Converters class object. The functions of
1580 this object returns always a string.
1581
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001582.. js:attribute:: TXN.f
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001583
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001584 :returns: An :ref:`fetches_class`.
1585
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001586 This attribute contains a Fetches class object.
1587
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001588.. js:attribute:: TXN.sf
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001589
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001590 :returns: An :ref:`fetches_class`.
1591
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001592 This attribute contains a Fetches class object. The functions of
1593 this object returns always a string.
1594
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001595.. js:attribute:: TXN.req
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001596
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001597 :returns: An :ref:`channel_class`.
1598
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001599 This attribute contains a channel class object for the request buffer.
1600
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001601.. js:attribute:: TXN.res
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001602
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001603 :returns: An :ref:`channel_class`.
1604
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001605 This attribute contains a channel class object for the response buffer.
1606
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001607.. js:attribute:: TXN.http
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001608
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001609 :returns: An :ref:`http_class`.
1610
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001611 This attribute contains an HTTP class object. It is available only if the
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001612 proxy has the "mode http" enabled.
1613
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001614.. js:function:: TXN.log(TXN, loglevel, msg)
1615
1616 This function sends a log. The log is sent, according with the HAProxy
1617 configuration file, on the default syslog server if it is configured and on
1618 the stderr if it is allowed.
1619
1620 :param class_txn txn: The class txn object containing the data.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001621 :param integer loglevel: Is the log level associated with the message. It is a
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001622 number between 0 and 7.
1623 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001624 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1625 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1626 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
1627 :see: :js:func:`TXN.deflog`
1628 :see: :js:func:`TXN.Debug`
1629 :see: :js:func:`TXN.Info`
1630 :see: :js:func:`TXN.Warning`
1631 :see: :js:func:`TXN.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001632
1633.. js:function:: TXN.deflog(TXN, msg)
1634
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001635 Sends a log line with the default loglevel for the proxy associated with the
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001636 transaction.
1637
1638 :param class_txn txn: The class txn object containing the data.
1639 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001640 :see: :js:func:`TXN.log
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001641
1642.. js:function:: TXN.Debug(txn, msg)
1643
1644 :param class_txn txn: The class txn object containing the data.
1645 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001646 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001647
1648 Does the same job than:
1649
1650.. code-block:: lua
1651
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001652 function Debug(txn, msg)
1653 TXN.log(txn, core.debug, msg)
1654 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001655..
1656
1657.. js:function:: TXN.Info(txn, msg)
1658
1659 :param class_txn txn: The class txn object containing the data.
1660 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001661 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001662
1663.. code-block:: lua
1664
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001665 function Debug(txn, msg)
1666 TXN.log(txn, core.info, msg)
1667 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001668..
1669
1670.. js:function:: TXN.Warning(txn, msg)
1671
1672 :param class_txn txn: The class txn object containing the data.
1673 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001674 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001675
1676.. code-block:: lua
1677
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001678 function Debug(txn, msg)
1679 TXN.log(txn, core.warning, msg)
1680 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001681..
1682
1683.. js:function:: TXN.Alert(txn, msg)
1684
1685 :param class_txn txn: The class txn object containing the data.
1686 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001687 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001688
1689.. code-block:: lua
1690
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001691 function Debug(txn, msg)
1692 TXN.log(txn, core.alert, msg)
1693 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001694..
1695
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001696.. js:function:: TXN.get_priv(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001697
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001698 Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001699 function. If no data are stored, it returns a nil value.
1700
1701 :param class_txn txn: The class txn object containing the data.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001702 :returns: the opaque data previously stored, or nil if nothing is
1703 available.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001704
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001705.. js:function:: TXN.set_priv(txn, data)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001706
1707 Store any data in the current HAProxy transaction. This action replace the
1708 old stored data.
1709
1710 :param class_txn txn: The class txn object containing the data.
1711 :param opaque data: The data which is stored in the transaction.
1712
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001713.. js:function:: TXN.set_var(TXN, var, value)
1714
David Carlier61fdf8b2015-10-02 11:59:38 +01001715 Converts a Lua type in a HAProxy type and store it in a variable <var>.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001716
1717 :param class_txn txn: The class txn object containing the data.
1718 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER / OZON.IOb210bcc2016-12-12 16:24:16 +01001719 :param type value: The value associated to the variable. The type can be string or
1720 integer.
Christopher Faulet85d79c92016-11-09 16:54:56 +01001721
1722.. js:function:: TXN.unset_var(TXN, var)
1723
1724 Unset the variable <var>.
1725
1726 :param class_txn txn: The class txn object containing the data.
1727 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001728
1729.. js:function:: TXN.get_var(TXN, var)
1730
1731 Returns data stored in the variable <var> converter in Lua type.
1732
1733 :param class_txn txn: The class txn object containing the data.
1734 :param string var: The variable name according with the HAProxy variable syntax.
1735
Christopher Faulet700d9e82020-01-31 12:21:52 +01001736.. js:function:: TXN.reply([reply])
1737
1738 Return a new reply object
1739
1740 :param table reply: A table containing info to initialize the reply fields.
1741 :returns: A :ref:`reply_class` object.
1742
1743 The table used to initialized the reply object may contain following entries :
1744
1745 * status : The reply status code. the code 200 is used by default.
1746 * reason : The reply reason. The reason corresponding to the status code is
1747 used by default.
1748 * headers : An list of headers, indexed by header name. Empty by default. For
1749 a given name, multiple values are possible, stored in an ordered list.
1750 * body : The reply body, empty by default.
1751
1752.. code-block:: lua
1753
1754 local reply = txn:reply{
1755 status = 400,
1756 reason = "Bad request",
1757 headers = {
1758 ["content-type"] = { "text/html" },
1759 ["cache-control"] = {"no-cache", "no-store" }
1760 },
1761 body = "<html><body><h1>invalid request<h1></body></html>"
1762 }
1763..
1764 :see: :js:class:`Reply`
1765
1766.. js:function:: TXN.done(txn[, reply])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001767
Willy Tarreaubc183a62015-08-28 10:39:11 +02001768 This function terminates processing of the transaction and the associated
Christopher Faulet700d9e82020-01-31 12:21:52 +01001769 session and optionally reply to the client for HTTP sessions.
1770
1771 :param class_txn txn: The class txn object containing the data.
1772 :param class_reply reply: The class reply object to return to the client.
1773
1774 This functions can be used when a critical error is detected or to terminate
Willy Tarreaubc183a62015-08-28 10:39:11 +02001775 processing after some data have been returned to the client (eg: a redirect).
Christopher Faulet700d9e82020-01-31 12:21:52 +01001776 To do so, a reply may be provided. This object is optional and may contain a
1777 status code, a reason, a header list and a body. All these fields are
1778 optionnals. When not provided, the default values are used. By default, with
1779 an empty reply object, an empty HTTP 200 response is returned to the
1780 client. If no reply object is provided, the transaction is terminated without
1781 any reply.
1782
1783 The reply object may be fully created in lua or the class Reply may be used to
1784 create it.
1785
1786.. code-block:: lua
1787
1788 local reply = txn:reply()
1789 reply:set_status(400, "Bad request")
1790 reply:add_header("content-type", "text/html")
1791 reply:add_header("cache-control", "no-cache")
1792 reply:add_header("cache-control", "no-store")
1793 reply:set_body("<html><body><h1>invalid request<h1></body></html>")
1794 txn:done(reply)
1795..
1796
1797.. code-block:: lua
1798
1799 txn:done{
1800 status = 400,
1801 reason = "Bad request",
1802 headers = {
1803 ["content-type"] = { "text/html" },
1804 ["cache-control"] = { "no-cache", "no-store" },
1805 },
1806 body = "<html><body><h1>invalid request<h1></body></html>"
1807 }
1808..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001809
Thierry FOURNIERab00df62016-07-14 11:42:37 +02001810 *Warning*: It not make sense to call this function from sample-fetches. In
1811 this case the behaviour of this one is the same than core.done(): it quit
1812 the Lua execution. The transaction is really aborted only from an action
1813 registered function.
1814
Christopher Faulet700d9e82020-01-31 12:21:52 +01001815 :see: :js:func:`TXN.reply`, :js:class:`Reply`
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001816
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001817.. js:function:: TXN.set_loglevel(txn, loglevel)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001818
1819 Is used to change the log level of the current request. The "loglevel" must
1820 be an integer between 0 and 7.
1821
1822 :param class_txn txn: The class txn object containing the data.
1823 :param integer loglevel: The required log level. This variable can be one of
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001824 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1825 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1826 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001827
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001828.. js:function:: TXN.set_tos(txn, tos)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001829
1830 Is used to set the TOS or DSCP field value of packets sent to the client to
1831 the value passed in "tos" on platforms which support this.
1832
1833 :param class_txn txn: The class txn object containing the data.
1834 :param integer tos: The new TOS os DSCP.
1835
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001836.. js:function:: TXN.set_mark(txn, mark)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001837
1838 Is used to set the Netfilter MARK on all packets sent to the client to the
1839 value passed in "mark" on platforms which support it.
1840
1841 :param class_txn txn: The class txn object containing the data.
1842 :param integer mark: The mark value.
1843
Patrick Hemmer268a7072018-05-11 12:52:31 -04001844.. js:function:: TXN.set_priority_class(txn, prio)
1845
1846 This function adjusts the priority class of the transaction. The value should
1847 be within the range -2047..2047. Values outside this range will be
1848 truncated.
1849
1850 See the HAProxy configuration.txt file keyword "http-request" action
1851 "set-priority-class" for details.
1852
1853.. js:function:: TXN.set_priority_offset(txn, prio)
1854
1855 This function adjusts the priority offset of the transaction. The value
1856 should be within the range -524287..524287. Values outside this range will be
1857 truncated.
1858
1859 See the HAProxy configuration.txt file keyword "http-request" action
1860 "set-priority-offset" for details.
1861
Christopher Faulet700d9e82020-01-31 12:21:52 +01001862.. _reply_class:
1863
1864Reply class
1865============
1866
1867.. js:class:: Reply
1868
1869 **context**: action
1870
1871 This class represents an HTTP response message. It provides some methods to
1872 enrich it.
1873
1874.. code-block:: lua
1875
1876 local reply = txn:reply({status = 400}) -- default HTTP 400 reason-phase used
1877 reply:add_header("content-type", "text/html")
1878 reply:add_header("cache-control", "no-cache")
1879 reply:add_header("cache-control", "no-store")
1880 reply:set_body("<html><body><h1>invalid request<h1></body></html>")
1881..
1882
1883 :see: :js:func:`TXN.reply`
1884
1885.. js:attribute:: Reply.status
1886
1887 The reply status code. By default, the status code is set to 200.
1888
1889 :returns: integer
1890
1891.. js:attribute:: Reply.reason
1892
1893 The reason string describing the status code.
1894
1895 :returns: string
1896
1897.. js:attribute:: Reply.headers
1898
1899 A table indexing all reply headers by name. To each name is associated an
1900 ordered list of values.
1901
1902 :returns: Lua table
1903
1904.. code-block:: lua
1905
1906 {
1907 ["content-type"] = { "text/html" },
1908 ["cache-control"] = {"no-cache", "no-store" },
1909 x_header_name = { "value1", "value2", ... }
1910 ...
1911 }
1912..
1913
1914.. js:attribute:: Reply.body
1915
1916 The reply payload.
1917
1918 :returns: string
1919
1920.. js:function:: Reply.set_status(REPLY, status[, reason])
1921
1922 Set the reply status code and optionally the reason-phrase. If the reason is
1923 not provided, the default reason corresponding to the status code is used.
1924
1925 :param class_reply reply: The related Reply object.
1926 :param integer status: The reply status code.
1927 :param string reason: The reply status reason (optional).
1928
1929.. js:function:: Reply.add_header(REPLY, name, value)
1930
1931 Add a header to the reply object. If the header does not already exist, a new
1932 entry is created with its name as index and a one-element list containing its
1933 value as value. Otherwise, the header value is appended to the ordered list of
1934 values associated to the header name.
1935
1936 :param class_reply reply: The related Reply object.
1937 :param string name: The header field name.
1938 :param string value: The header field value.
1939
1940.. js:function:: Reply.del_header(REPLY, name)
1941
1942 Remove all occurrences of a header name from the reply object.
1943
1944 :param class_reply reply: The related Reply object.
1945 :param string name: The header field name.
1946
1947.. js:function:: Reply.set_body(REPLY, body)
1948
1949 Set the reply payload.
1950
1951 :param class_reply reply: The related Reply object.
1952 :param string body: The reply payload.
1953
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001954.. _socket_class:
1955
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001956Socket class
1957============
1958
1959.. js:class:: Socket
1960
1961 This class must be compatible with the Lua Socket class. Only the 'client'
1962 functions are available. See the Lua Socket documentation:
1963
1964 `http://w3.impa.br/~diego/software/luasocket/tcp.html
1965 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
1966
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001967.. js:function:: Socket.close(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001968
1969 Closes a TCP object. The internal socket used by the object is closed and the
1970 local address to which the object was bound is made available to other
1971 applications. No further operations (except for further calls to the close
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001972 method) are allowed on a closed Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001973
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001974 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001975
1976 Note: It is important to close all used sockets once they are not needed,
1977 since, in many systems, each socket uses a file descriptor, which are limited
1978 system resources. Garbage-collected objects are automatically closed before
1979 destruction, though.
1980
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001981.. js:function:: Socket.connect(socket, address[, port])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001982
1983 Attempts to connect a socket object to a remote host.
1984
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001985
1986 In case of error, the method returns nil followed by a string describing the
1987 error. In case of success, the method returns 1.
1988
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001989 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001990 :param string address: can be an IP address or a host name. See below for more
1991 information.
1992 :param integer port: must be an integer number in the range [1..64K].
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001993 :returns: 1 or nil.
1994
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001995 An address field extension permits to use the connect() function to connect to
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001996 other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is
1997 the basically expected format. This format requires the port.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001998
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001999 Other format accepted are a socket path like "/socket/path", it permits to
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002000 connect to a socket. Abstract namespaces are supported with the prefix
Joseph Herlant02cedc42018-11-13 19:45:17 -08002001 "abns@", and finally a file descriptor can be passed with the prefix "fd@".
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002002 The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002003 passed int the string. The syntax "127.0.0.1:1234" is valid. In this case, the
Tim Duesterhus6edab862018-01-06 19:04:45 +01002004 parameter *port* must not be set.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002005
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002006.. js:function:: Socket.connect_ssl(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002007
2008 Same behavior than the function socket:connect, but uses SSL.
2009
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002010 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002011 :returns: 1 or nil.
2012
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002013.. js:function:: Socket.getpeername(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002014
2015 Returns information about the remote side of a connected client object.
2016
2017 Returns a string with the IP address of the peer, followed by the port number
2018 that peer is using for the connection. In case of error, the method returns
2019 nil.
2020
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002021 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002022 :returns: a string containing the server information.
2023
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002024.. js:function:: Socket.getsockname(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002025
2026 Returns the local address information associated to the object.
2027
2028 The method returns a string with local IP address and a number with the port.
2029 In case of error, the method returns nil.
2030
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002031 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002032 :returns: a string containing the client information.
2033
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002034.. js:function:: Socket.receive(socket, [pattern [, prefix]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002035
2036 Reads data from a client object, according to the specified read pattern.
2037 Patterns follow the Lua file I/O format, and the difference in performance
2038 between all patterns is negligible.
2039
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002040 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002041 :param string|integer pattern: Describe what is required (see below).
2042 :param string prefix: A string which will be prefix the returned data.
2043 :returns: a string containing the required data or nil.
2044
2045 Pattern can be any of the following:
2046
2047 * **`*a`**: reads from the socket until the connection is closed. No
2048 end-of-line translation is performed;
2049
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002050 * **`*l`**: reads a line of text from the Socket. The line is terminated by a
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002051 LF character (ASCII 10), optionally preceded by a CR character
2052 (ASCII 13). The CR and LF characters are not included in the
2053 returned line. In fact, all CR characters are ignored by the
2054 pattern. This is the default pattern.
2055
2056 * **number**: causes the method to read a specified number of bytes from the
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002057 Socket. Prefix is an optional string to be concatenated to the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002058 beginning of any received data before return.
2059
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002060 * **empty**: If the pattern is left empty, the default option is `*l`.
2061
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002062 If successful, the method returns the received pattern. In case of error, the
2063 method returns nil followed by an error message which can be the string
2064 'closed' in case the connection was closed before the transmission was
2065 completed or the string 'timeout' in case there was a timeout during the
2066 operation. Also, after the error message, the function returns the partial
2067 result of the transmission.
2068
2069 Important note: This function was changed severely. It used to support
2070 multiple patterns (but I have never seen this feature used) and now it
2071 doesn't anymore. Partial results used to be returned in the same way as
2072 successful results. This last feature violated the idea that all functions
2073 should return nil on error. Thus it was changed too.
2074
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002075.. js:function:: Socket.send(socket, data [, start [, end ]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002076
2077 Sends data through client object.
2078
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002079 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002080 :param string data: The data that will be sent.
2081 :param integer start: The start position in the buffer of the data which will
2082 be sent.
2083 :param integer end: The end position in the buffer of the data which will
2084 be sent.
2085 :returns: see below.
2086
2087 Data is the string to be sent. The optional arguments i and j work exactly
2088 like the standard string.sub Lua function to allow the selection of a
2089 substring to be sent.
2090
2091 If successful, the method returns the index of the last byte within [start,
2092 end] that has been sent. Notice that, if start is 1 or absent, this is
2093 effectively the total number of bytes sent. In case of error, the method
2094 returns nil, followed by an error message, followed by the index of the last
2095 byte within [start, end] that has been sent. You might want to try again from
2096 the byte following that. The error message can be 'closed' in case the
2097 connection was closed before the transmission was completed or the string
2098 'timeout' in case there was a timeout during the operation.
2099
2100 Note: Output is not buffered. For small strings, it is always better to
2101 concatenate them in Lua (with the '..' operator) and send the result in one
2102 call instead of calling the method several times.
2103
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002104.. js:function:: Socket.setoption(socket, option [, value])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002105
2106 Just implemented for compatibility, this cal does nothing.
2107
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002108.. js:function:: Socket.settimeout(socket, value [, mode])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002109
2110 Changes the timeout values for the object. All I/O operations are blocking.
2111 That is, any call to the methods send, receive, and accept will block
2112 indefinitely, until the operation completes. The settimeout method defines a
2113 limit on the amount of time the I/O methods can block. When a timeout time
2114 has elapsed, the affected methods give up and fail with an error code.
2115
2116 The amount of time to wait is specified as the value parameter, in seconds.
2117
Mark Lakes56cc1252018-03-27 09:48:06 +02002118 The timeout modes are not implemented, the only settable timeout is the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002119 inactivity time waiting for complete the internal buffer send or waiting for
2120 receive data.
2121
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002122 :param class_socket socket: Is the manipulated Socket.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002123 :param float value: The timeout value. Use floating point to specify
Mark Lakes56cc1252018-03-27 09:48:06 +02002124 milliseconds.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002125
Thierry FOURNIER31904272017-10-25 12:59:51 +02002126.. _regex_class:
2127
2128Regex class
2129===========
2130
2131.. js:class:: Regex
2132
2133 This class allows the usage of HAProxy regexes because classic lua doesn't
2134 provides regexes. This class inherits the HAProxy compilation options, so the
2135 regexes can be libc regex, pcre regex or pcre JIT regex.
2136
2137 The expression matching number is limited to 20 per regex. The only available
2138 option is case sensitive.
2139
2140 Because regexes compilation is a heavy process, it is better to define all
2141 your regexes in the **body context** and use it during the runtime.
2142
2143.. code-block:: lua
2144
2145 -- Create the regex
2146 st, regex = Regex.new("needle (..) (...)", true);
2147
2148 -- Check compilation errors
2149 if st == false then
2150 print "error: " .. regex
2151 end
2152
2153 -- Match the regexes
2154 print(regex:exec("Looking for a needle in the haystack")) -- true
2155 print(regex:exec("Lokking for a cat in the haystack")) -- false
2156
2157 -- Extract words
2158 st, list = regex:match("Looking for a needle in the haystack")
2159 print(st) -- true
2160 print(list[1]) -- needle in the
2161 print(list[2]) -- in
2162 print(list[3]) -- the
2163
2164.. js:function:: Regex.new(regex, case_sensitive)
2165
2166 Create and compile a regex.
2167
2168 :param string regex: The regular expression according with the libc or pcre
2169 standard
2170 :param boolean case_sensitive: Match is case sensitive or not.
2171 :returns: boolean status and :ref:`regex_class` or string containing fail reason.
2172
2173.. js:function:: Regex.exec(regex, str)
2174
2175 Execute the regex.
2176
2177 :param class_regex regex: A :ref:`regex_class` object.
2178 :param string str: The input string will be compared with the compiled regex.
2179 :returns: a boolean status according with the match result.
2180
2181.. js:function:: Regex.match(regex, str)
2182
2183 Execute the regex and return matched expressions.
2184
2185 :param class_map map: A :ref:`regex_class` object.
2186 :param string str: The input string will be compared with the compiled regex.
2187 :returns: a boolean status according with the match result, and
2188 a table containing all the string matched in order of declaration.
2189
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002190.. _map_class:
2191
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002192Map class
2193=========
2194
2195.. js:class:: Map
2196
2197 This class permits to do some lookup in HAProxy maps. The declared maps can
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002198 be modified during the runtime through the HAProxy management socket.
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002199
2200.. code-block:: lua
2201
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002202 default = "usa"
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002203
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002204 -- Create and load map
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002205 geo = Map.new("geo.map", Map._ip);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002206
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002207 -- Create new fetch that returns the user country
2208 core.register_fetches("country", function(txn)
2209 local src;
2210 local loc;
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002211
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002212 src = txn.f:fhdr("x-forwarded-for");
2213 if (src == nil) then
2214 src = txn.f:src()
2215 if (src == nil) then
2216 return default;
2217 end
2218 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002219
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002220 -- Perform lookup
2221 loc = geo:lookup(src);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002222
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002223 if (loc == nil) then
2224 return default;
2225 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002226
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002227 return loc;
2228 end);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002229
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002230.. js:attribute:: Map._int
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002231
2232 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002233 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002234 method.
2235
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002236 Note that :js:attr:`Map.int` is also available for compatibility.
2237
2238.. js:attribute:: Map._ip
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002239
2240 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002241 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002242 method.
2243
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002244 Note that :js:attr:`Map.ip` is also available for compatibility.
2245
2246.. js:attribute:: Map._str
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002247
2248 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002249 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002250 method.
2251
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002252 Note that :js:attr:`Map.str` is also available for compatibility.
2253
2254.. js:attribute:: Map._beg
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002255
2256 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002257 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002258 method.
2259
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002260 Note that :js:attr:`Map.beg` is also available for compatibility.
2261
2262.. js:attribute:: Map._sub
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002263
2264 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002265 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002266 method.
2267
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002268 Note that :js:attr:`Map.sub` is also available for compatibility.
2269
2270.. js:attribute:: Map._dir
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002271
2272 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002273 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002274 method.
2275
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002276 Note that :js:attr:`Map.dir` is also available for compatibility.
2277
2278.. js:attribute:: Map._dom
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002279
2280 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002281 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002282 method.
2283
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002284 Note that :js:attr:`Map.dom` is also available for compatibility.
2285
2286.. js:attribute:: Map._end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002287
2288 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002289 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002290 method.
2291
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002292.. js:attribute:: Map._reg
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002293
2294 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002295 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002296 method.
2297
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002298 Note that :js:attr:`Map.reg` is also available for compatibility.
2299
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002300
2301.. js:function:: Map.new(file, method)
2302
2303 Creates and load a map.
2304
2305 :param string file: Is the file containing the map.
2306 :param integer method: Is the map pattern matching method. See the attributes
2307 of the Map class.
2308 :returns: a class Map object.
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002309 :see: The Map attributes: :js:attr:`Map._int`, :js:attr:`Map._ip`,
2310 :js:attr:`Map._str`, :js:attr:`Map._beg`, :js:attr:`Map._sub`,
2311 :js:attr:`Map._dir`, :js:attr:`Map._dom`, :js:attr:`Map._end` and
2312 :js:attr:`Map._reg`.
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002313
2314.. js:function:: Map.lookup(map, str)
2315
2316 Perform a lookup in a map.
2317
2318 :param class_map map: Is the class Map object.
2319 :param string str: Is the string used as key.
2320 :returns: a string containing the result or nil if no match.
2321
2322.. js:function:: Map.slookup(map, str)
2323
2324 Perform a lookup in a map.
2325
2326 :param class_map map: Is the class Map object.
2327 :param string str: Is the string used as key.
2328 :returns: a string containing the result or empty string if no match.
2329
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002330.. _applethttp_class:
2331
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002332AppletHTTP class
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002333================
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002334
2335.. js:class:: AppletHTTP
2336
2337 This class is used with applets that requires the 'http' mode. The http applet
2338 can be registered with the *core.register_service()* function. They are used
2339 for processing an http request like a server in back of HAProxy.
2340
2341 This is an hello world sample code:
2342
2343.. code-block:: lua
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002344
Pieter Baauw4d7f7662015-11-08 16:38:08 +01002345 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002346 local response = "Hello World !"
2347 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02002348 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002349 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02002350 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002351 applet:send(response)
2352 end)
2353
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002354.. js:attribute:: AppletHTTP.c
2355
2356 :returns: A :ref:`converters_class`
2357
2358 This attribute contains a Converters class object.
2359
2360.. js:attribute:: AppletHTTP.sc
2361
2362 :returns: A :ref:`converters_class`
2363
2364 This attribute contains a Converters class object. The
2365 functions of this object returns always a string.
2366
2367.. js:attribute:: AppletHTTP.f
2368
2369 :returns: A :ref:`fetches_class`
2370
2371 This attribute contains a Fetches class object. Note that the
2372 applet execution place cannot access to a valid HAProxy core HTTP
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002373 transaction, so some sample fetches related to the HTTP dependent
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002374 values (hdr, path, ...) are not available.
2375
2376.. js:attribute:: AppletHTTP.sf
2377
2378 :returns: A :ref:`fetches_class`
2379
2380 This attribute contains a Fetches class object. The functions of
2381 this object returns always a string. Note that the applet
2382 execution place cannot access to a valid HAProxy core HTTP
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002383 transaction, so some sample fetches related to the HTTP dependent
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002384 values (hdr, path, ...) are not available.
2385
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002386.. js:attribute:: AppletHTTP.method
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002387
2388 :returns: string
2389
2390 The attribute method returns a string containing the HTTP
2391 method.
2392
2393.. js:attribute:: AppletHTTP.version
2394
2395 :returns: string
2396
2397 The attribute version, returns a string containing the HTTP
2398 request version.
2399
2400.. js:attribute:: AppletHTTP.path
2401
2402 :returns: string
2403
2404 The attribute path returns a string containing the HTTP
2405 request path.
2406
2407.. js:attribute:: AppletHTTP.qs
2408
2409 :returns: string
2410
2411 The attribute qs returns a string containing the HTTP
2412 request query string.
2413
2414.. js:attribute:: AppletHTTP.length
2415
2416 :returns: integer
2417
2418 The attribute length returns an integer containing the HTTP
2419 body length.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002420
Thierry FOURNIER841475e2015-12-11 17:10:09 +01002421.. js:attribute:: AppletHTTP.headers
2422
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04002423 :returns: table
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002424
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04002425 The attribute headers returns a table containing the HTTP
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002426 headers. The header names are always in lower case. As the header name can be
2427 encountered more than once in each request, the value is indexed with 0 as
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04002428 first index value. The table have this form:
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002429
2430.. code-block:: lua
2431
2432 AppletHTTP.headers['<header-name>'][<header-index>] = "<header-value>"
2433
2434 AppletHTTP.headers["host"][0] = "www.test.com"
2435 AppletHTTP.headers["accept"][0] = "audio/basic q=1"
2436 AppletHTTP.headers["accept"][1] = "audio/*, q=0.2"
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002437 AppletHTTP.headers["accept"][2] = "*/*, q=0.1"
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002438..
2439
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002440.. js:function:: AppletHTTP.set_status(applet, code [, reason])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002441
2442 This function sets the HTTP status code for the response. The allowed code are
2443 from 100 to 599.
2444
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002445 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002446 :param integer code: the status code returned to the client.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002447 :param string reason: the status reason returned to the client (optional).
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002448
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002449.. js:function:: AppletHTTP.add_header(applet, name, value)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002450
2451 This function add an header in the response. Duplicated headers are not
2452 collapsed. The special header *content-length* is used to determinate the
2453 response length. If it not exists, a *transfer-encoding: chunked* is set, and
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002454 all the write from the function *AppletHTTP:send()* become a chunk.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002455
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002456 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002457 :param string name: the header name
2458 :param string value: the header value
2459
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002460.. js:function:: AppletHTTP.start_response(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002461
2462 This function indicates to the HTTP engine that it can process and send the
2463 response headers. After this called we cannot add headers to the response; We
2464 cannot use the *AppletHTTP:send()* function if the
2465 *AppletHTTP:start_response()* is not called.
2466
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002467 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2468
2469.. js:function:: AppletHTTP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002470
2471 This function returns a string containing one line from the http body. If the
2472 data returned doesn't contains a final '\\n' its assumed than its the last
2473 available data before the end of stream.
2474
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002475 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002476 :returns: a string. The string can be empty if we reach the end of the stream.
2477
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002478.. js:function:: AppletHTTP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002479
2480 Reads data from the HTTP body, according to the specified read *size*. If the
2481 *size* is missing, the function tries to read all the content of the stream
2482 until the end. If the *size* is bigger than the http body, it returns the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002483 amount of data available.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002484
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002485 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002486 :param integer size: the required read size.
2487 :returns: always return a string,the string can be empty is the connexion is
2488 closed.
2489
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002490.. js:function:: AppletHTTP.send(applet, msg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002491
2492 Send the message *msg* on the http request body.
2493
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002494 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002495 :param string msg: the message to send.
2496
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002497.. js:function:: AppletHTTP.get_priv(applet)
2498
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002499 Return Lua data stored in the current transaction. If no data are stored,
2500 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002501
2502 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002503 :returns: the opaque data previously stored, or nil if nothing is
2504 available.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002505 :see: :js:func:`AppletHTTP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002506
2507.. js:function:: AppletHTTP.set_priv(applet, data)
2508
2509 Store any data in the current HAProxy transaction. This action replace the
2510 old stored data.
2511
2512 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2513 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002514 :see: :js:func:`AppletHTTP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002515
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002516.. js:function:: AppletHTTP.set_var(applet, var, value)
2517
2518 Converts a Lua type in a HAProxy type and store it in a variable <var>.
2519
2520 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2521 :param string var: The variable name according with the HAProxy variable syntax.
2522 :param type value: The value associated to the variable. The type ca be string or
2523 integer.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002524 :see: :js:func:`AppletHTTP.unset_var`
2525 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002526
2527.. js:function:: AppletHTTP.unset_var(applet, var)
2528
2529 Unset the variable <var>.
2530
2531 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2532 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002533 :see: :js:func:`AppletHTTP.set_var`
2534 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002535
2536.. js:function:: AppletHTTP.get_var(applet, var)
2537
2538 Returns data stored in the variable <var> converter in Lua type.
2539
2540 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2541 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002542 :see: :js:func:`AppletHTTP.set_var`
2543 :see: :js:func:`AppletHTTP.unset_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002544
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002545.. _applettcp_class:
2546
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002547AppletTCP class
2548===============
2549
2550.. js:class:: AppletTCP
2551
2552 This class is used with applets that requires the 'tcp' mode. The tcp applet
2553 can be registered with the *core.register_service()* function. They are used
2554 for processing a tcp stream like a server in back of HAProxy.
2555
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002556.. js:attribute:: AppletTCP.c
2557
2558 :returns: A :ref:`converters_class`
2559
2560 This attribute contains a Converters class object.
2561
2562.. js:attribute:: AppletTCP.sc
2563
2564 :returns: A :ref:`converters_class`
2565
2566 This attribute contains a Converters class object. The
2567 functions of this object returns always a string.
2568
2569.. js:attribute:: AppletTCP.f
2570
2571 :returns: A :ref:`fetches_class`
2572
2573 This attribute contains a Fetches class object.
2574
2575.. js:attribute:: AppletTCP.sf
2576
2577 :returns: A :ref:`fetches_class`
2578
2579 This attribute contains a Fetches class object.
2580
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002581.. js:function:: AppletTCP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002582
2583 This function returns a string containing one line from the stream. If the
2584 data returned doesn't contains a final '\\n' its assumed than its the last
2585 available data before the end of stream.
2586
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002587 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002588 :returns: a string. The string can be empty if we reach the end of the stream.
2589
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002590.. js:function:: AppletTCP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002591
2592 Reads data from the TCP stream, according to the specified read *size*. If the
2593 *size* is missing, the function tries to read all the content of the stream
2594 until the end.
2595
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002596 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002597 :param integer size: the required read size.
2598 :returns: always return a string,the string can be empty is the connexion is
2599 closed.
2600
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002601.. js:function:: AppletTCP.send(appletmsg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002602
2603 Send the message on the stream.
2604
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002605 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002606 :param string msg: the message to send.
2607
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002608.. js:function:: AppletTCP.get_priv(applet)
2609
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002610 Return Lua data stored in the current transaction. If no data are stored,
2611 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002612
2613 :param class_AppletTCP applet: An :ref:`applettcp_class`
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002614 :returns: the opaque data previously stored, or nil if nothing is
2615 available.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002616 :see: :js:func:`AppletTCP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002617
2618.. js:function:: AppletTCP.set_priv(applet, data)
2619
2620 Store any data in the current HAProxy transaction. This action replace the
2621 old stored data.
2622
2623 :param class_AppletTCP applet: An :ref:`applettcp_class`
2624 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002625 :see: :js:func:`AppletTCP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002626
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002627.. js:function:: AppletTCP.set_var(applet, var, value)
2628
2629 Converts a Lua type in a HAProxy type and stores it in a variable <var>.
2630
2631 :param class_AppletTCP applet: An :ref:`applettcp_class`
2632 :param string var: The variable name according with the HAProxy variable syntax.
2633 :param type value: The value associated to the variable. The type can be string or
2634 integer.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002635 :see: :js:func:`AppletTCP.unset_var`
2636 :see: :js:func:`AppletTCP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002637
2638.. js:function:: AppletTCP.unset_var(applet, var)
2639
2640 Unsets the variable <var>.
2641
2642 :param class_AppletTCP applet: An :ref:`applettcp_class`
2643 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002644 :see: :js:func:`AppletTCP.unset_var`
2645 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002646
2647.. js:function:: AppletTCP.get_var(applet, var)
2648
2649 Returns data stored in the variable <var> converter in Lua type.
2650
2651 :param class_AppletTCP applet: An :ref:`applettcp_class`
2652 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002653 :see: :js:func:`AppletTCP.unset_var`
2654 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002655
Adis Nezirovic8878f8e2018-07-13 12:18:33 +02002656StickTable class
2657================
2658
2659.. js:class:: StickTable
2660
2661 **context**: task, action, sample-fetch
2662
2663 This class can be used to access the HAProxy stick tables from Lua.
2664
2665.. js:function:: StickTable.info()
2666
2667 Returns stick table attributes as a Lua table. See HAProxy documentation for
2668 "stick-table" for canonical info, or check out example bellow.
2669
2670 :returns: Lua table
2671
2672 Assume our table has IPv4 key and gpc0 and conn_rate "columns":
2673
2674.. code-block:: lua
2675
2676 {
2677 expire=<int>, # Value in ms
2678 size=<int>, # Maximum table size
2679 used=<int>, # Actual number of entries in table
2680 data={ # Data columns, with types as key, and periods as values
2681 (-1 if type is not rate counter)
2682 conn_rate=<int>,
2683 gpc0=-1
2684 },
2685 length=<int>, # max string length for string table keys, key length
2686 # otherwise
2687 nopurge=<boolean>, # purge oldest entries when table is full
2688 type="ip" # can be "ip", "ipv6", "integer", "string", "binary"
2689 }
2690
2691.. js:function:: StickTable.lookup(key)
2692
2693 Returns stick table entry for given <key>
2694
2695 :param string key: Stick table key (IP addresses and strings are supported)
2696 :returns: Lua table
2697
2698.. js:function:: StickTable.dump([filter])
2699
2700 Returns all entries in stick table. An optional filter can be used
2701 to extract entries with specific data values. Filter is a table with valid
2702 comparison operators as keys followed by data type name and value pairs.
2703 Check out the HAProxy docs for "show table" for more details. For the
2704 reference, the supported operators are:
2705 "eq", "ne", "le", "lt", "ge", "gt"
2706
2707 For large tables, execution of this function can take a long time (for
2708 HAProxy standards). That's also true when filter is used, so take care and
2709 measure the impact.
2710
2711 :param table filter: Stick table filter
2712 :returns: Stick table entries (table)
2713
2714 See below for example filter, which contains 4 entries (or comparisons).
2715 (Maximum number of filter entries is 4, defined in the source code)
2716
2717.. code-block:: lua
2718
2719 local filter = {
2720 {"gpc0", "gt", 30}, {"gpc1", "gt", 20}}, {"conn_rate", "le", 10}
2721 }
2722
Christopher Faulet0f3c8902020-01-31 18:57:12 +01002723.. _action_class:
2724
2725Action class
2726=============
2727
2728.. js:class:: Act
2729
2730 **context**: action
2731
2732 This class contains all return codes an action may return. It is the lua
2733 equivalent to HAProxy "ACT_RET_*" code.
2734
2735.. code-block:: lua
2736
2737 core.register_action("deny", { "http-req" }, function (txn)
2738 return act.DENY
2739 end)
2740..
2741.. js:attribute:: act.CONTINUE
2742
2743 This attribute is an integer (0). It instructs HAProxy to continue the current
2744 ruleset processing on the message. It is the default return code for a lua
2745 action.
2746
2747 :returns: integer
2748
2749.. js:attribute:: act.STOP
2750
2751 This attribute is an integer (1). It instructs HAProxy to stop the current
2752 ruleset processing on the message.
2753
2754.. js:attribute:: act.YIELD
2755
2756 This attribute is an integer (2). It instructs HAProxy to temporarily pause
2757 the message processing. It will be resumed later on the same rule. The
2758 corresponding lua script is re-executed for the start.
2759
2760.. js:attribute:: act.ERROR
2761
2762 This attribute is an integer (3). It triggers an internal errors The message
2763 processing is stopped and the transaction is terminated. For HTTP streams, an
2764 HTTP 500 error is returned to the client.
2765
2766 :returns: integer
2767
2768.. js:attribute:: act.DONE
2769
2770 This attribute is an integer (4). It instructs HAProxy to stop the message
2771 processing.
2772
2773 :returns: integer
2774
2775.. js:attribute:: act.DENY
2776
2777 This attribute is an integer (5). It denies the current message. The message
2778 processing is stopped and the transaction is terminated. For HTTP streams, an
2779 HTTP 403 error is returned to the client if the deny is returned during the
2780 request analysis. During the response analysis, an HTTP 502 error is returned
2781 and the server response is discarded.
2782
2783 :returns: integer
2784
2785.. js:attribute:: act.ABORT
2786
2787 This attribute is an integer (6). It aborts the current message. The message
2788 processing is stopped and the transaction is terminated. For HTTP streams,
2789 HAproxy assumes a response was already sent to the client. From the Lua
2790 actions point of view, when this code is used, the transaction is terminated
2791 with no reply.
2792
2793 :returns: integer
2794
2795.. js:attribute:: act.INVALID
2796
2797 This attribute is an integer (7). It triggers an internal errors. The message
2798 processing is stopped and the transaction is terminated. For HTTP streams, an
2799 HTTP 400 error is returned to the client if the error is returned during the
2800 request analysis. During the response analysis, an HTTP 502 error is returned
2801 and the server response is discarded.
2802
2803 :returns: integer
Adis Nezirovic8878f8e2018-07-13 12:18:33 +02002804
Christopher Faulet2c2c2e32020-01-31 19:07:52 +01002805.. js:function:: act:wake_time(milliseconds)
2806
2807 **context**: action
2808
2809 Set the script pause timeout to the specified time, defined in
2810 milliseconds.
2811
2812 :param integer milliseconds: the required milliseconds.
2813
2814 This function may be used when a lua action returns `act.YIELD`, to force its
2815 wake-up at most after the specified number of milliseconds.
2816
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002817External Lua libraries
2818======================
2819
2820A lot of useful lua libraries can be found here:
2821
2822* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_
2823
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002824Redis client library:
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002825
2826* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
2827
2828This is an example about the usage of the Redis library with HAProxy. Note that
2829each call of any function of this library can throw an error if the socket
2830connection fails.
2831
2832.. code-block:: lua
2833
2834 -- load the redis library
2835 local redis = require("redis");
2836
2837 function do_something(txn)
2838
2839 -- create and connect new tcp socket
2840 local tcp = core.tcp();
2841 tcp:settimeout(1);
2842 tcp:connect("127.0.0.1", 6379);
2843
2844 -- use the redis library with this new socket
2845 local client = redis.connect({socket=tcp});
2846 client:ping();
2847
2848 end
2849
2850OpenSSL:
2851
2852* `http://mkottman.github.io/luacrypto/index.html
2853 <http://mkottman.github.io/luacrypto/index.html>`_
2854
2855* `https://github.com/brunoos/luasec/wiki
2856 <https://github.com/brunoos/luasec/wiki>`_