blob: e04c5b5a75a7b2f7a14c399669cf5e8ca5c3841c [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
172 This attribute is an array of declared proxies (frontend and backends). Each
173 proxy give an access to his list of listeners and servers. Each entry is of
174 type :ref:`proxy_class`
175
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100176.. js:function:: core.log(loglevel, msg)
177
178 **context**: body, init, task, action, sample-fetch, converter
179
David Carlier61fdf8b2015-10-02 11:59:38 +0100180 This function sends a log. The log is sent, according with the HAProxy
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100181 configuration file, on the default syslog server if it is configured and on
182 the stderr if it is allowed.
183
184 :param integer loglevel: Is the log level asociated with the message. It is a
185 number between 0 and 7.
186 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100187 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
188 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
189 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
190 :see: :js:func:`core.Debug`
191 :see: :js:func:`core.Info`
192 :see: :js:func:`core.Warning`
193 :see: :js:func:`core.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100194
195.. js:function:: core.Debug(msg)
196
197 **context**: body, init, task, action, sample-fetch, converter
198
199 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100200 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100201
202 Does the same job than:
203
204.. code-block:: lua
205
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100206 function Debug(msg)
207 core.log(core.debug, msg)
208 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100209..
210
211.. js:function:: core.Info(msg)
212
213 **context**: body, init, task, action, sample-fetch, converter
214
215 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100216 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100217
218.. code-block:: lua
219
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100220 function Info(msg)
221 core.log(core.info, msg)
222 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100223..
224
225.. js:function:: core.Warning(msg)
226
227 **context**: body, init, task, action, sample-fetch, converter
228
229 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100230 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100231
232.. code-block:: lua
233
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100234 function Warning(msg)
235 core.log(core.warning, msg)
236 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100237..
238
239.. js:function:: core.Alert(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 Alert(msg)
249 core.log(core.alert, msg)
250 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100251..
252
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100253.. js:function:: core.add_acl(filename, key)
254
255 **context**: init, task, action, sample-fetch, converter
256
257 Add the ACL *key* in the ACLs list referenced by the file *filename*.
258
259 :param string filename: the filename that reference the ACL entries.
260 :param string key: the key which will be added.
261
262.. js:function:: core.del_acl(filename, key)
263
264 **context**: init, task, action, sample-fetch, converter
265
266 Delete the ACL entry referenced by the key *key* in the list of ACLs
267 referenced by *filename*.
268
269 :param string filename: the filename that reference the ACL entries.
270 :param string key: the key which will be deleted.
271
272.. js:function:: core.del_map(filename, key)
273
274 **context**: init, task, action, sample-fetch, converter
275
276 Delete the map entry indexed with the specified key in the list of maps
277 referenced by his filename.
278
279 :param string filename: the filename that reference the map entries.
280 :param string key: the key which will be deleted.
281
Thierry Fourniereea77c02016-03-18 08:47:13 +0100282.. js:function:: core.get_info()
283
284 **context**: body, init, task, action, sample-fetch, converter
285
286 Returns HAProxy core informations. We can found information like the uptime,
287 the pid, memory pool usage, tasks number, ...
288
289 These information are also returned by the management sockat via the command
290 "show info". See the management socket documentation fpor more information
291 about the content of these variables.
292
293 :returns: an array of values.
294
Thierry Fournierb1f46562016-01-21 09:46:15 +0100295.. js:function:: core.now()
296
297 **context**: body, init, task, action
298
299 This function returns the current time. The time returned is fixed by the
300 HAProxy core and assures than the hour will be monotnic and that the system
301 call 'gettimeofday' will not be called too. The time is refreshed between each
302 Lua execution or resume, so two consecutive call to the function "now" will
303 probably returns the same result.
304
305 :returns: an array which contains two entries "sec" and "usec". "sec"
306 contains the current at the epoch format, and "usec" contains the
307 current microseconds.
308
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100309.. js:function:: core.http_date(date)
310
311 **context**: body, init, task, action
312
313 This function take a string repsenting http date, and returns an integer
314 containing the corresponding date with a epoch format. A valid http date
315 me respect the format IMF, RFC850 or ASCTIME.
316
317 :param string date: a date http-date formatted
318 :returns: integer containing epoch date
319 :see: :js:func:`core.imf_date`.
320 :see: :js:func:`core.rfc850_date`.
321 :see: :js:func:`core.asctime_date`.
322 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
323
324.. js:function:: core.imf_date(date)
325
326 **context**: body, init, task, action
327
328 This function take a string repsenting IMF date, and returns an integer
329 containing the corresponding date with a epoch format.
330
331 :param string date: a date IMF formatted
332 :returns: integer containing epoch date
333 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
334
335 The IMF format is like this:
336
337.. code-block:: text
338
339 Sun, 06 Nov 1994 08:49:37 GMT
340..
341
342.. js:function:: core.rfc850_date(date)
343
344 **context**: body, init, task, action
345
346 This function take a string repsenting RFC850 date, and returns an integer
347 containing the corresponding date with a epoch format.
348
349 :param string date: a date RFC859 formatted
350 :returns: integer containing epoch date
351 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
352
353 The RFC850 format is like this:
354
355.. code-block:: text
356
357 Sunday, 06-Nov-94 08:49:37 GMT
358..
359
360.. js:function:: core.asctime_date(date)
361
362 **context**: body, init, task, action
363
364 This function take a string repsenting ASCTIME date, and returns an integer
365 containing the corresponding date with a epoch format.
366
367 :param string date: a date ASCTIME formatted
368 :returns: integer containing epoch date
369 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
370
371 The ASCTIME format is like this:
372
373.. code-block:: text
374
375 Sun Nov 6 08:49:37 1994
376..
377
378.. js:function:: core.rfc850_date(date)
379
380 **context**: body, init, task, action
381
382 This function take a string repsenting http date, and returns an integer
383 containing the corresponding date with a epoch format.
384
385 :param string date: a date http-date formatted
386
387.. js:function:: core.asctime_date(date)
388
389 **context**: body, init, task, action
390
391 This function take a string repsenting http date, and returns an integer
392 containing the corresponding date with a epoch format.
393
394 :param string date: a date http-date formatted
395
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100396.. js:function:: core.msleep(milliseconds)
397
398 **context**: body, init, task, action
399
400 The `core.msleep()` stops the Lua execution between specified milliseconds.
401
402 :param integer milliseconds: the required milliseconds.
403
Thierry Fournierf61aa632016-02-19 20:56:00 +0100404.. js:attribute:: core.proxies
405
406 **context**: body, init, task, action, sample-fetch, converter
407
408 proxies is an array containing the list of all proxies declared in the
409 configuration file. Each entry of the proxies array is an object of type
410 :ref:`proxy_class`
411
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200412.. js:function:: core.register_action(name, actions, func)
413
414 **context**: body
415
David Carlier61fdf8b2015-10-02 11:59:38 +0100416 Register a Lua function executed as action. All the registered action can be
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200417 used in HAProxy with the prefix "lua.". An action gets a TXN object class as
418 input.
419
420 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200421 :param table actions: is a table of string describing the HAProxy actions who
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200422 want to register to. The expected actions are 'tcp-req',
423 'tcp-res', 'http-req' or 'http-res'.
424 :param function func: is the Lua function called to work as converter.
425
426 The prototype of the Lua function used as argument is:
427
428.. code-block:: lua
429
430 function(txn)
431..
432
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100433 * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200434 current request or TCP stream.
435
Willy Tarreau61add3c2015-09-28 15:39:10 +0200436 Here, an exemple of action registration. the action juste send an 'Hello world'
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200437 in the logs.
438
439.. code-block:: lua
440
441 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
442 txn:Info("Hello world")
443 end)
444..
445
446 This example code is used in HAproxy configuration like this:
447
448::
449
450 frontend tcp_frt
451 mode tcp
452 tcp-request content lua.hello-world
453
454 frontend http_frt
455 mode http
456 http-request lua.hello-world
457
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100458.. js:function:: core.register_converters(name, func)
459
460 **context**: body
461
David Carlier61fdf8b2015-10-02 11:59:38 +0100462 Register a Lua function executed as converter. All the registered converters
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100463 can be used in HAProxy with the prefix "lua.". An converter get a string as
464 input and return a string as output. The registered function can take up to 9
465 values as parameter. All the value are strings.
466
467 :param string name: is the name of the converter.
468 :param function func: is the Lua function called to work as converter.
469
470 The prototype of the Lua function used as argument is:
471
472.. code-block:: lua
473
474 function(str, [p1 [, p2 [, ... [, p5]]]])
475..
476
477 * **str** (*string*): this is the input value automatically converted in
478 string.
479 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
480 the haroxy configuration file. The number of arguments doesn't exceed 5.
481 The order and the nature of these is conventionally choose by the
482 developper.
483
484.. js:function:: core.register_fetches(name, func)
485
486 **context**: body
487
David Carlier61fdf8b2015-10-02 11:59:38 +0100488 Register a Lua function executed as sample fetch. All the registered sample
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100489 fetchs can be used in HAProxy with the prefix "lua.". A Lua sample fetch
490 return a string as output. The registered function can take up to 9 values as
491 parameter. All the value are strings.
492
493 :param string name: is the name of the converter.
494 :param function func: is the Lua function called to work as sample fetch.
495
496 The prototype of the Lua function used as argument is:
497
498.. code-block:: lua
499
500 string function(txn, [p1 [, p2 [, ... [, p5]]]])
501..
502
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100503 * **txn** (:ref:`txn_class`): this is the txn object associated with the current
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100504 request.
505 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
506 the haroxy configuration file. The number of arguments doesn't exceed 5.
507 The order and the nature of these is conventionally choose by the
508 developper.
509 * **Returns**: A string containing some data, ot nil if the value cannot be
510 returned now.
511
512 lua example code:
513
514.. code-block:: lua
515
516 core.register_fetches("hello", function(txn)
517 return "hello"
518 end)
519..
520
521 HAProxy example configuration:
522
523::
524
525 frontend example
526 http-request redirect location /%[lua.hello]
527
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200528.. js:function:: core.register_service(name, mode, func)
529
530 **context**: body
531
David Carlier61fdf8b2015-10-02 11:59:38 +0100532 Register a Lua function executed as a service. All the registered service can
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200533 be used in HAProxy with the prefix "lua.". A service gets an object class as
534 input according with the required mode.
535
536 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200537 :param string mode: is string describing the required mode. Only 'tcp' or
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200538 'http' are allowed.
539 :param function func: is the Lua function called to work as converter.
540
541 The prototype of the Lua function used as argument is:
542
543.. code-block:: lua
544
545 function(applet)
546..
547
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100548 * **applet** *applet* will be a :ref:`applettcp_class` or a
549 :ref:`applethttp_class`. It depends the type of registered applet. An applet
550 registered with the 'http' value for the *mode* parameter will gets a
551 :ref:`applethttp_class`. If the *mode* value is 'tcp', the applet will gets
552 a :ref:`applettcp_class`.
553
554 **warning**: Applets of type 'http' cannot be called from 'tcp-*'
555 rulesets. Only the 'http-*' rulesets are authorized, this means
556 that is not possible to call an HTTP applet from a proxy in tcp
557 mode. Applets of type 'tcp' can be called from anywhre.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200558
Willy Tarreau61add3c2015-09-28 15:39:10 +0200559 Here, an exemple of service registration. the service just send an 'Hello world'
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200560 as an http response.
561
562.. code-block:: lua
563
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100564 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200565 local response = "Hello World !"
566 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200567 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200568 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200569 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200570 applet:send(response)
571 end)
572..
573
574 This example code is used in HAproxy configuration like this:
575
576::
577
578 frontend example
579 http-request use-service lua.hello-world
580
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100581.. js:function:: core.register_init(func)
582
583 **context**: body
584
585 Register a function executed after the configuration parsing. This is useful
586 to check any parameters.
587
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100588 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100589
590 The prototype of the Lua function used as argument is:
591
592.. code-block:: lua
593
594 function()
595..
596
597 It takes no input, and no output is expected.
598
599.. js:function:: core.register_task(func)
600
601 **context**: body, init, task, action, sample-fetch, converter
602
603 Register and start independent task. The task is started when the HAProxy
604 main scheduler starts. For example this type of tasks can be executed to
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100605 perform complex health checks.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100606
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100607 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100608
609 The prototype of the Lua function used as argument is:
610
611.. code-block:: lua
612
613 function()
614..
615
616 It takes no input, and no output is expected.
617
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100618.. js:function:: core.register_cli([path], usage, func)
619
620 **context**: body
621
622 Register and start independent task. The task is started when the HAProxy
623 main scheduler starts. For example this type of tasks can be executed to
624 perform complex health checks.
625
626 :param array path: is the sequence of word for which the cli execute the Lua
627 binding.
628 :param string usage: is the usage message displayed in the help.
629 :param function func: is the Lua function called to handle the CLI commands.
630
631 The prototype of the Lua function used as argument is:
632
633.. code-block:: lua
634
635 function(AppletTCP, [arg1, [arg2, [...]]])
636..
637
638 I/O are managed with the :ref:`applettcp_class` object. Args are given as
639 paramter. The args embbed the registred path. If the path is declared like
640 this:
641
642.. code-block:: lua
643
644 core.register_cli({"show", "ssl", "stats"}, "Display SSL stats..", function(applet, arg1, arg2, arg3, arg4, arg5)
645 end)
646..
647
648 And we execute this in the prompt:
649
650.. code-block:: text
651
652 > prompt
653 > show ssl stats all
654..
655
656 Then, arg1, arg2 and arg3 will contains respectivey "show", "ssl" and "stats".
657 arg4 will contain "all". arg5 contains nil.
658
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100659.. js:function:: core.set_nice(nice)
660
661 **context**: task, action, sample-fetch, converter
662
663 Change the nice of the current task or current session.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100664
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100665 :param integer nice: the nice value, it must be between -1024 and 1024.
666
667.. js:function:: core.set_map(filename, key, value)
668
669 **context**: init, task, action, sample-fetch, converter
670
671 set the value *value* associated to the key *key* in the map referenced by
672 *filename*.
673
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100674 :param string filename: the Map reference
675 :param string key: the key to set or replace
676 :param string value: the associated value
677
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100678.. js:function:: core.sleep(int seconds)
679
680 **context**: body, init, task, action
681
682 The `core.sleep()` functions stop the Lua execution between specified seconds.
683
684 :param integer seconds: the required seconds.
685
686.. js:function:: core.tcp()
687
688 **context**: init, task, action
689
690 This function returns a new object of a *socket* class.
691
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100692 :returns: A :ref:`socket_class` object.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100693
Thierry Fournier1de16592016-01-27 09:49:07 +0100694.. js:function:: core.concat()
695
696 **context**: body, init, task, action, sample-fetch, converter
697
698 This function retruns a new concat object.
699
700 :returns: A :ref:`concat_class` object.
701
Thierry FOURNIER0a99b892015-08-26 00:14:17 +0200702.. js:function:: core.done(data)
703
704 **context**: body, init, task, action, sample-fetch, converter
705
706 :param any data: Return some data for the caller. It is useful with
707 sample-fetches and sample-converters.
708
709 Immediately stops the current Lua execution and returns to the caller which
710 may be a sample fetch, a converter or an action and returns the specified
711 value (ignored for actions). It is used when the LUA process finishes its
712 work and wants to give back the control to HAProxy without executing the
713 remaining code. It can be seen as a multi-level "return".
714
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100715.. js:function:: core.yield()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100716
717 **context**: task, action, sample-fetch, converter
718
719 Give back the hand at the HAProxy scheduler. It is used when the LUA
720 processing consumes a lot of processing time.
721
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100722.. js:function:: core.parse_addr(address)
723
724 **context**: body, init, task, action, sample-fetch, converter
725
726 :param network: is a string describing an ipv4 or ipv6 address and optionally
727 its network length, like this: "127.0.0.1/8" or "aaaa::1234/32".
728 :returns: a userdata containing network or nil if an error occurs.
729
730 Parse ipv4 or ipv6 adresses and its facultative associated network.
731
732.. js:function:: core.match_addr(addr1, addr2)
733
734 **context**: body, init, task, action, sample-fetch, converter
735
736 :param addr1: is an address created with "core.parse_addr".
737 :param addr2: is an address created with "core.parse_addr".
738 :returns: boolean, true if the network of the addresses matche, else returns
739 false.
740
741 Match two networks. For example "127.0.0.1/32" matchs "127.0.0.0/8". The order
742 of network is not important.
743
Thierry FOURNIER / OZON.IO8a1027a2016-11-24 20:48:38 +0100744.. js:function:: core.tokenize(str, separators [, noblank])
745
746 **context**: body, init, task, action, sample-fetch, converter
747
748 This function is useful for tokenizing an entry, or splitting some messages.
749 :param string str: The string which will be split.
750 :param string separators: A string containing a list of separators.
751 :param boolean noblank: Ignore empty entries.
752 :returns: an array of string.
753
754 For example:
755
756.. code-block:: lua
757
758 local array = core.tokenize("This function is useful, for tokenizing an entry.", "., ", true)
759 print_r(array)
760..
761
762 Returns this array:
763
764.. code-block:: text
765
766 (table) table: 0x21c01e0 [
767 1: (string) "This"
768 2: (string) "function"
769 3: (string) "is"
770 4: (string) "useful"
771 5: (string) "for"
772 6: (string) "tokenizing"
773 7: (string) "an"
774 8: (string) "entry"
775 ]
776..
777
Thierry Fournierf61aa632016-02-19 20:56:00 +0100778.. _proxy_class:
779
780Proxy class
781============
782
783.. js:class:: Proxy
784
785 This class provides a way for manipulating proxy and retrieving information
786 like statistics.
787
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100788.. js:attribute:: Proxy.servers
789
790 Contain an array with the attached servers. Each server entry is an object of
791 type :ref:`server_class`.
792
Thierry Fournierff480422016-02-25 08:36:46 +0100793.. js:attribute:: Proxy.listeners
794
795 Contain an array with the attached listeners. Each listeners entry is an
796 object of type :ref:`listener_class`.
797
Thierry Fournierf61aa632016-02-19 20:56:00 +0100798.. js:function:: Proxy.pause(px)
799
800 Pause the proxy. See the management socket documentation for more information.
801
802 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
803 proxy.
804
805.. js:function:: Proxy.resume(px)
806
807 Resume the proxy. See the management socket documentation for more
808 information.
809
810 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
811 proxy.
812
813.. js:function:: Proxy.stop(px)
814
815 Stop the proxy. See the management socket documentation for more information.
816
817 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
818 proxy.
819
820.. js:function:: Proxy.shut_bcksess(px)
821
822 Kill the session attached to a backup server. See the management socket
823 documentation for more information.
824
825 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
826 proxy.
827
828.. js:function:: Proxy.get_cap(px)
829
830 Returns a string describing the capabilities of the proxy.
831
832 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
833 proxy.
834 :returns: a string "frontend", "backend", "proxy" or "ruleset".
835
836.. js:function:: Proxy.get_mode(px)
837
838 Returns a string describing the mode of the current proxy.
839
840 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
841 proxy.
842 :returns: a string "tcp", "http", "health" or "unknown"
843
844.. js:function:: Proxy.get_stats(px)
845
846 Returns an array containg the proxy statistics. The statistics returned are
847 not the same if the proxy is frontend or a backend.
848
849 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
850 proxy.
851 :returns: a key/value array containing stats
852
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100853.. _server_class:
854
855Server class
856============
857
858.. js:function:: Server.is_draining(sv)
859
860 Return true if the server is currently draining stiky connections.
861
862 :param class_server sv: A :ref:`server_class` which indicates the manipulated
863 server.
864 :returns: a boolean
865
866.. js:function:: Server.set_weight(sv, weight)
867
868 Dynamically change the weight of the serveur. See the management socket
869 documentation for more information about the format of the string.
870
871 :param class_server sv: A :ref:`server_class` which indicates the manipulated
872 server.
873 :param string weight: A string describing the server weight.
874
875.. js:function:: Server.get_weight(sv)
876
877 This function returns an integer representing the serveur weight.
878
879 :param class_server sv: A :ref:`server_class` which indicates the manipulated
880 server.
881 :returns: an integer.
882
883.. js:function:: Server.set_addr(sv, addr)
884
885 Dynamically change the address of the serveur. See the management socket
886 documentation for more information about the format of the string.
887
888 :param class_server sv: A :ref:`server_class` which indicates the manipulated
889 server.
890 :param string weight: A string describing the server address.
891
892.. js:function:: Server.get_addr(sv)
893
894 Returns a string describing the address of the serveur.
895
896 :param class_server sv: A :ref:`server_class` which indicates the manipulated
897 server.
898 :returns: A string
899
900.. js:function:: Server.get_stats(sv)
901
902 Returns server statistics.
903
904 :param class_server sv: A :ref:`server_class` which indicates the manipulated
905 server.
906 :returns: a key/value array containing stats
907
908.. js:function:: Server.shut_sess(sv)
909
910 Shutdown all the sessions attached to the server. See the management socket
911 documentation for more information about this function.
912
913 :param class_server sv: A :ref:`server_class` which indicates the manipulated
914 server.
915
916.. js:function:: Server.set_drain(sv)
917
918 Drain sticky sessions. See the management socket documentation for more
919 information about this function.
920
921 :param class_server sv: A :ref:`server_class` which indicates the manipulated
922 server.
923
924.. js:function:: Server.set_maint(sv)
925
926 Set maintenance mode. See the management socket documentation for more
927 information about this function.
928
929 :param class_server sv: A :ref:`server_class` which indicates the manipulated
930 server.
931
932.. js:function:: Server.set_ready(sv)
933
934 Set normal mode. See the management socket documentation for more information
935 about this function.
936
937 :param class_server sv: A :ref:`server_class` which indicates the manipulated
938 server.
939
940.. js:function:: Server.check_enable(sv)
941
942 Enable health checks. See the management socket documentation for more
943 information about this function.
944
945 :param class_server sv: A :ref:`server_class` which indicates the manipulated
946 server.
947
948.. js:function:: Server.check_disable(sv)
949
950 Disable health checks. See the management socket documentation for more
951 information about this function.
952
953 :param class_server sv: A :ref:`server_class` which indicates the manipulated
954 server.
955
956.. js:function:: Server.check_force_up(sv)
957
958 Force health-check up. See the management socket documentation for more
959 information about this function.
960
961 :param class_server sv: A :ref:`server_class` which indicates the manipulated
962 server.
963
964.. js:function:: Server.check_force_nolb(sv)
965
966 Force health-check nolb mode. See the management socket documentation for more
967 information about this function.
968
969 :param class_server sv: A :ref:`server_class` which indicates the manipulated
970 server.
971
972.. js:function:: Server.check_force_down(sv)
973
974 Force health-check down. See the management socket documentation for more
975 information about this function.
976
977 :param class_server sv: A :ref:`server_class` which indicates the manipulated
978 server.
979
980.. js:function:: Server.agent_enable(sv)
981
982 Enable agent check. See the management socket documentation for more
983 information about this function.
984
985 :param class_server sv: A :ref:`server_class` which indicates the manipulated
986 server.
987
988.. js:function:: Server.agent_disable(sv)
989
990 Disable agent check. See the management socket documentation for more
991 information about this function.
992
993 :param class_server sv: A :ref:`server_class` which indicates the manipulated
994 server.
995
996.. js:function:: Server.agent_force_up(sv)
997
998 Force agent check up. See the management socket documentation for more
999 information about this function.
1000
1001 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1002 server.
1003
1004.. js:function:: Server.agent_force_down(sv)
1005
1006 Force agent check down. See the management socket documentation for more
1007 information about this function.
1008
1009 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1010 server.
1011
Thierry Fournierff480422016-02-25 08:36:46 +01001012.. _listener_class:
1013
1014Listener class
1015==============
1016
1017.. js:function:: Listener.get_stats(ls)
1018
1019 Returns server statistics.
1020
1021 :param class_listener ls: A :ref:`listener_class` which indicates the
1022 manipulated listener.
1023 :returns: a key/value array containing stats
1024
Thierry Fournier1de16592016-01-27 09:49:07 +01001025.. _concat_class:
1026
1027Concat class
1028============
1029
1030.. js:class:: Concat
1031
1032 This class provides a fast way for string concatenation. The way using native
1033 Lua concatenation like the code below is slow for some reasons.
1034
1035.. code-block:: lua
1036
1037 str = "string1"
1038 str = str .. ", string2"
1039 str = str .. ", string3"
1040..
1041
1042 For each concatenation, Lua:
1043 * allocate memory for the result,
1044 * catenate the two string copying the strings in the new memory bloc,
1045 * free the old memory block containing the string whoch is no longer used.
1046 This process does many memory move, allocation and free. In addition, the
1047 memory is not really freed, it is just mark mark as unsused and wait for the
1048 garbage collector.
1049
1050 The Concat class provide an alternative way for catenating strings. It uses
1051 the internal Lua mechanism (it does not allocate memory), but it doesn't copy
1052 the data more than once.
1053
1054 On my computer, the following loops spends 0.2s for the Concat method and
1055 18.5s for the pure Lua implementation. So, the Concat class is about 1000x
1056 faster than the embedded solution.
1057
1058.. code-block:: lua
1059
1060 for j = 1, 100 do
1061 c = core.concat()
1062 for i = 1, 20000 do
1063 c:add("#####")
1064 end
1065 end
1066..
1067
1068.. code-block:: lua
1069
1070 for j = 1, 100 do
1071 c = ""
1072 for i = 1, 20000 do
1073 c = c .. "#####"
1074 end
1075 end
1076..
1077
1078.. js:function:: Concat.add(concat, string)
1079
1080 This function adds a string to the current concatenated string.
1081
1082 :param class_concat concat: A :ref:`concat_class` which contains the currently
1083 builded string.
1084 :param string string: A new string to concatenate to the current builded
1085 string.
1086
1087.. js:function:: Concat.dump(concat)
1088
1089 This function returns the concanated string.
1090
1091 :param class_concat concat: A :ref:`concat_class` which contains the currently
1092 builded string.
1093 :returns: the concatenated string
1094
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001095.. _fetches_class:
1096
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001097Fetches class
1098=============
1099
1100.. js:class:: Fetches
1101
1102 This class contains a lot of internal HAProxy sample fetches. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001103 HAProxy "configuration.txt" documentation for more information about her
1104 usage. they are the chapters 7.3.2 to 7.3.6.
1105
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001106 **warning** some sample fetches are not available in some context. These
1107 limitations are specified in this documentation when theire useful.
1108
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001109 :see: :js:attr:`TXN.f`
1110 :see: :js:attr:`TXN.sf`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001111
1112 Fetches are useful for:
1113
1114 * get system time,
1115 * get environment variable,
1116 * get random numbers,
1117 * known backend status like the number of users in queue or the number of
1118 connections established,
1119 * client information like ip source or destination,
1120 * deal with stick tables,
1121 * Established SSL informations,
1122 * HTTP information like headers or method.
1123
1124.. code-block:: lua
1125
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001126 function action(txn)
1127 -- Get source IP
1128 local clientip = txn.f:src()
1129 end
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001130..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001131
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001132.. _converters_class:
1133
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001134Converters class
1135================
1136
1137.. js:class:: Converters
1138
1139 This class contains a lot of internal HAProxy sample converters. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001140 HAProxy documentation "configuration.txt" for more information about her
1141 usage. Its the chapter 7.3.1.
1142
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001143 :see: :js:attr:`TXN.c`
1144 :see: :js:attr:`TXN.sc`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001145
1146 Converters provides statefull transformation. They are useful for:
1147
1148 * converting input to base64,
1149 * applying hash on input string (djb2, crc32, sdbm, wt6),
1150 * format date,
1151 * json escape,
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001152 * extracting preferred language comparing two lists,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001153 * turn to lower or upper chars,
1154 * deal with stick tables.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001155
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001156.. _channel_class:
1157
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001158Channel class
1159=============
1160
1161.. js:class:: Channel
1162
1163 HAProxy uses two buffers for the processing of the requests. The first one is
1164 used with the request data (from the client to the server) and the second is
1165 used for the response data (from the server to the client).
1166
1167 Each buffer contains two types of data. The first type is the incoming data
1168 waiting for a processing. The second part is the outgoing data already
1169 processed. Usually, the incoming data is processed, after it is tagged as
1170 outgoing data, and finally it is sent. The following functions provides tools
1171 for manipulating these data in a buffer.
1172
1173 The following diagram shows where the channel class function are applied.
1174
1175 **Warning**: It is not possible to read from the response in request action,
1176 and it is not possible to read for the request channel in response action.
1177
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001178.. image:: _static/channel.png
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001179
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001180.. js:function:: Channel.dup(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001181
1182 This function returns a string that contain the entire buffer. The data is
1183 not remove from the buffer and can be reprocessed later.
1184
1185 If the buffer cant receive more data, a 'nil' value is returned.
1186
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001187 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001188 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001189
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001190.. js:function:: Channel.get(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001191
1192 This function returns a string that contain the entire buffer. The data is
1193 consumed from the buffer.
1194
1195 If the buffer cant receive more data, a 'nil' value is returned.
1196
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001197 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001198 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001199
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001200.. js:function:: Channel.getline(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001201
1202 This function returns a string that contain the first line of the buffer. The
1203 data is consumed. If the data returned doesn't contains a final '\n' its
1204 assumed than its the last available data in the buffer.
1205
1206 If the buffer cant receive more data, a 'nil' value is returned.
1207
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001208 :param class_channel channel: The manipulated Channel.
Pieter Baauw386a1272015-08-16 15:26:24 +02001209 :returns: a string containing the available line or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001210
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001211.. js:function:: Channel.set(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001212
1213 This function replace the content of the buffer by the string. The function
1214 returns the copied length, otherwise, it returns -1.
1215
1216 The data set with this function are not send. They wait for the end of
1217 HAProxy processing, so the buffer can be full.
1218
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001219 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001220 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001221 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001222
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001223.. js:function:: Channel.append(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001224
1225 This function append the string argument to the content of the buffer. The
1226 function returns the copied length, otherwise, it returns -1.
1227
1228 The data set with this function are not send. They wait for the end of
1229 HAProxy processing, so the buffer can be full.
1230
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001231 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001232 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001233 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001234
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001235.. js:function:: Channel.send(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001236
1237 This function required immediate send of the data. Unless if the connection
1238 is close, the buffer is regularly flushed and all the string can be sent.
1239
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001240 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001241 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001242 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001243
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001244.. js:function:: Channel.get_in_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001245
1246 This function returns the length of the input part of the buffer.
1247
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001248 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001249 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001250
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001251.. js:function:: Channel.get_out_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001252
1253 This function returns the length of the output part of the buffer.
1254
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001255 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001256 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001257
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001258.. js:function:: Channel.forward(channel, int)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001259
1260 This function transfer bytes from the input part of the buffer to the output
1261 part.
1262
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001263 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001264 :param integer int: The amount of data which will be forwarded.
1265
Thierry FOURNIER / OZON.IO65192f32016-11-07 15:28:40 +01001266.. js:function:: Channel.is_full(channel)
1267
1268 This function returns true if the buffer channel is full.
1269
1270 :returns: a boolean
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001271
1272.. _http_class:
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001273
1274HTTP class
1275==========
1276
1277.. js:class:: HTTP
1278
1279 This class contain all the HTTP manipulation functions.
1280
Pieter Baauw386a1272015-08-16 15:26:24 +02001281.. js:function:: HTTP.req_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001282
1283 Returns an array containing all the request headers.
1284
1285 :param class_http http: The related http object.
1286 :returns: array of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001287 :see: :js:func:`HTTP.res_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001288
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001289 This is the form of the returned array:
1290
1291.. code-block:: lua
1292
1293 HTTP:req_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1294
1295 local hdr = HTTP:req_get_headers()
1296 hdr["host"][0] = "www.test.com"
1297 hdr["accept"][0] = "audio/basic q=1"
1298 hdr["accept"][1] = "audio/*, q=0.2"
1299 hdr["accept"][2] = "*/*, q=0.1"
1300..
1301
Pieter Baauw386a1272015-08-16 15:26:24 +02001302.. js:function:: HTTP.res_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001303
1304 Returns an array containing all the response headers.
1305
1306 :param class_http http: The related http object.
1307 :returns: array of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001308 :see: :js:func:`HTTP.req_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001309
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001310 This is the form of the returned array:
1311
1312.. code-block:: lua
1313
1314 HTTP:res_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1315
1316 local hdr = HTTP:req_get_headers()
1317 hdr["host"][0] = "www.test.com"
1318 hdr["accept"][0] = "audio/basic q=1"
1319 hdr["accept"][1] = "audio/*, q=0.2"
1320 hdr["accept"][2] = "*.*, q=0.1"
1321..
1322
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001323.. js:function:: HTTP.req_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001324
1325 Appends an HTTP header field in the request whose name is
1326 specified in "name" and whose value is defined in "value".
1327
1328 :param class_http http: The related http object.
1329 :param string name: The header name.
1330 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001331 :see: :js:func:`HTTP.res_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001332
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001333.. js:function:: HTTP.res_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001334
1335 appends an HTTP header field in the response whose name is
1336 specified in "name" and whose value is defined in "value".
1337
1338 :param class_http http: The related http object.
1339 :param string name: The header name.
1340 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001341 :see: :js:func:`HTTP.req_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001342
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001343.. js:function:: HTTP.req_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001344
1345 Removes all HTTP header fields in the request whose name is
1346 specified in "name".
1347
1348 :param class_http http: The related http object.
1349 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001350 :see: :js:func:`HTTP.res_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001351
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001352.. js:function:: HTTP.res_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001353
1354 Removes all HTTP header fields in the response whose name is
1355 specified in "name".
1356
1357 :param class_http http: The related http object.
1358 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001359 :see: :js:func:`HTTP.req_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001360
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001361.. js:function:: HTTP.req_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001362
1363 This variable replace all occurence of all header "name", by only
1364 one containing the "value".
1365
1366 :param class_http http: The related http object.
1367 :param string name: The header name.
1368 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001369 :see: :js:func:`HTTP.res_set_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001370
1371 This function does the same work as the folowwing code:
1372
1373.. code-block:: lua
1374
1375 function fcn(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001376 TXN.http:req_del_header("header")
1377 TXN.http:req_add_header("header", "value")
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001378 end
1379..
1380
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001381.. js:function:: HTTP.res_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001382
1383 This variable replace all occurence of all header "name", by only
1384 one containing the "value".
1385
1386 :param class_http http: The related http object.
1387 :param string name: The header name.
1388 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001389 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001390
Pieter Baauw386a1272015-08-16 15:26:24 +02001391.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001392
1393 Matches the regular expression in all occurrences of header field "name"
1394 according to "regex", and replaces them with the "replace" argument. The
1395 replacement value can contain back references like \1, \2, ... This
1396 function works with the request.
1397
1398 :param class_http http: The related http object.
1399 :param string name: The header name.
1400 :param string regex: The match regular expression.
1401 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001402 :see: :js:func:`HTTP.res_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001403
Pieter Baauw386a1272015-08-16 15:26:24 +02001404.. js:function:: HTTP.res_rep_header(http, name, regex, string)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001405
1406 Matches the regular expression in all occurrences of header field "name"
1407 according to "regex", and replaces them with the "replace" argument. The
1408 replacement value can contain back references like \1, \2, ... This
1409 function works with the request.
1410
1411 :param class_http http: The related http object.
1412 :param string name: The header name.
1413 :param string regex: The match regular expression.
1414 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001415 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001416
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001417.. js:function:: HTTP.req_set_method(http, method)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001418
1419 Rewrites the request method with the parameter "method".
1420
1421 :param class_http http: The related http object.
1422 :param string method: The new method.
1423
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001424.. js:function:: HTTP.req_set_path(http, path)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001425
1426 Rewrites the request path with the "path" parameter.
1427
1428 :param class_http http: The related http object.
1429 :param string path: The new path.
1430
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001431.. js:function:: HTTP.req_set_query(http, query)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001432
1433 Rewrites the request's query string which appears after the first question
1434 mark ("?") with the parameter "query".
1435
1436 :param class_http http: The related http object.
1437 :param string query: The new query.
1438
Thierry FOURNIER0d79cf62015-08-26 14:20:58 +02001439.. js:function:: HTTP.req_set_uri(http, uri)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001440
1441 Rewrites the request URI with the parameter "uri".
1442
1443 :param class_http http: The related http object.
1444 :param string uri: The new uri.
1445
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001446.. js:function:: HTTP.res_set_status(http, status [, reason])
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001447
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001448 Rewrites the response status code with the parameter "code".
1449
1450 If no custom reason is provided, it will be generated from the status.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001451
1452 :param class_http http: The related http object.
1453 :param integer status: The new response status code.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001454 :param string reason: The new response reason (optional).
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001455
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001456.. _txn_class:
1457
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001458TXN class
1459=========
1460
1461.. js:class:: TXN
1462
1463 The txn class contain all the functions relative to the http or tcp
1464 transaction (Note than a tcp stream is the same than a tcp transaction, but
1465 an HTTP transaction is not the same than a tcp stream).
1466
1467 The usage of this class permits to retrieve data from the requests, alter it
1468 and forward it.
1469
1470 All the functions provided by this class are available in the context
1471 **sample-fetches** and **actions**.
1472
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001473.. js:attribute:: TXN.c
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001474
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001475 :returns: An :ref:`converters_class`.
1476
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001477 This attribute contains a Converters class object.
1478
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001479.. js:attribute:: TXN.sc
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001480
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001481 :returns: An :ref:`converters_class`.
1482
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001483 This attribute contains a Converters class object. The functions of
1484 this object returns always a string.
1485
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001486.. js:attribute:: TXN.f
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001487
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001488 :returns: An :ref:`fetches_class`.
1489
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001490 This attribute contains a Fetches class object.
1491
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001492.. js:attribute:: TXN.sf
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001493
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001494 :returns: An :ref:`fetches_class`.
1495
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001496 This attribute contains a Fetches class object. The functions of
1497 this object returns always a string.
1498
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001499.. js:attribute:: TXN.req
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001500
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001501 :returns: An :ref:`channel_class`.
1502
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001503 This attribute contains a channel class object for the request buffer.
1504
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001505.. js:attribute:: TXN.res
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001506
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001507 :returns: An :ref:`channel_class`.
1508
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001509 This attribute contains a channel class object for the response buffer.
1510
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001511.. js:attribute:: TXN.http
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001512
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001513 :returns: An :ref:`http_class`.
1514
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001515 This attribute contains an HTTP class object. It is avalaible only if the
1516 proxy has the "mode http" enabled.
1517
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001518.. js:function:: TXN.log(TXN, loglevel, msg)
1519
1520 This function sends a log. The log is sent, according with the HAProxy
1521 configuration file, on the default syslog server if it is configured and on
1522 the stderr if it is allowed.
1523
1524 :param class_txn txn: The class txn object containing the data.
1525 :param integer loglevel: Is the log level asociated with the message. It is a
1526 number between 0 and 7.
1527 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001528 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1529 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1530 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
1531 :see: :js:func:`TXN.deflog`
1532 :see: :js:func:`TXN.Debug`
1533 :see: :js:func:`TXN.Info`
1534 :see: :js:func:`TXN.Warning`
1535 :see: :js:func:`TXN.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001536
1537.. js:function:: TXN.deflog(TXN, msg)
1538
1539 Sends a log line with the default loglevel for the proxy ssociated with the
1540 transaction.
1541
1542 :param class_txn txn: The class txn object containing the data.
1543 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001544 :see: :js:func:`TXN.log
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001545
1546.. js:function:: TXN.Debug(txn, msg)
1547
1548 :param class_txn txn: The class txn object containing the data.
1549 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001550 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001551
1552 Does the same job than:
1553
1554.. code-block:: lua
1555
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001556 function Debug(txn, msg)
1557 TXN.log(txn, core.debug, msg)
1558 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001559..
1560
1561.. js:function:: TXN.Info(txn, msg)
1562
1563 :param class_txn txn: The class txn object containing the data.
1564 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001565 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001566
1567.. code-block:: lua
1568
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001569 function Debug(txn, msg)
1570 TXN.log(txn, core.info, msg)
1571 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001572..
1573
1574.. js:function:: TXN.Warning(txn, msg)
1575
1576 :param class_txn txn: The class txn object containing the data.
1577 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001578 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001579
1580.. code-block:: lua
1581
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001582 function Debug(txn, msg)
1583 TXN.log(txn, core.warning, msg)
1584 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001585..
1586
1587.. js:function:: TXN.Alert(txn, msg)
1588
1589 :param class_txn txn: The class txn object containing the data.
1590 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001591 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001592
1593.. code-block:: lua
1594
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001595 function Debug(txn, msg)
1596 TXN.log(txn, core.alert, msg)
1597 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001598..
1599
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001600.. js:function:: TXN.get_priv(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001601
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001602 Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001603 function. If no data are stored, it returns a nil value.
1604
1605 :param class_txn txn: The class txn object containing the data.
1606 :returns: the opaque data previsously stored, or nil if nothing is
1607 avalaible.
1608
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001609.. js:function:: TXN.set_priv(txn, data)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001610
1611 Store any data in the current HAProxy transaction. This action replace the
1612 old stored data.
1613
1614 :param class_txn txn: The class txn object containing the data.
1615 :param opaque data: The data which is stored in the transaction.
1616
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001617.. js:function:: TXN.set_var(TXN, var, value)
1618
David Carlier61fdf8b2015-10-02 11:59:38 +01001619 Converts a Lua type in a HAProxy type and store it in a variable <var>.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001620
1621 :param class_txn txn: The class txn object containing the data.
1622 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER / OZON.IOb210bcc2016-12-12 16:24:16 +01001623 :param type value: The value associated to the variable. The type can be string or
1624 integer.
Christopher Faulet85d79c92016-11-09 16:54:56 +01001625
1626.. js:function:: TXN.unset_var(TXN, var)
1627
1628 Unset the variable <var>.
1629
1630 :param class_txn txn: The class txn object containing the data.
1631 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001632
1633.. js:function:: TXN.get_var(TXN, var)
1634
1635 Returns data stored in the variable <var> converter in Lua type.
1636
1637 :param class_txn txn: The class txn object containing the data.
1638 :param string var: The variable name according with the HAProxy variable syntax.
1639
Willy Tarreaubc183a62015-08-28 10:39:11 +02001640.. js:function:: TXN.done(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001641
Willy Tarreaubc183a62015-08-28 10:39:11 +02001642 This function terminates processing of the transaction and the associated
1643 session. It can be used when a critical error is detected or to terminate
1644 processing after some data have been returned to the client (eg: a redirect).
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001645
Thierry FOURNIERab00df62016-07-14 11:42:37 +02001646 *Warning*: It not make sense to call this function from sample-fetches. In
1647 this case the behaviour of this one is the same than core.done(): it quit
1648 the Lua execution. The transaction is really aborted only from an action
1649 registered function.
1650
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001651 :param class_txn txn: The class txn object containing the data.
1652
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001653.. js:function:: TXN.set_loglevel(txn, loglevel)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001654
1655 Is used to change the log level of the current request. The "loglevel" must
1656 be an integer between 0 and 7.
1657
1658 :param class_txn txn: The class txn object containing the data.
1659 :param integer loglevel: The required log level. This variable can be one of
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001660 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1661 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1662 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001663
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001664.. js:function:: TXN.set_tos(txn, tos)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001665
1666 Is used to set the TOS or DSCP field value of packets sent to the client to
1667 the value passed in "tos" on platforms which support this.
1668
1669 :param class_txn txn: The class txn object containing the data.
1670 :param integer tos: The new TOS os DSCP.
1671
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001672.. js:function:: TXN.set_mark(txn, mark)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001673
1674 Is used to set the Netfilter MARK on all packets sent to the client to the
1675 value passed in "mark" on platforms which support it.
1676
1677 :param class_txn txn: The class txn object containing the data.
1678 :param integer mark: The mark value.
1679
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001680.. _socket_class:
1681
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001682Socket class
1683============
1684
1685.. js:class:: Socket
1686
1687 This class must be compatible with the Lua Socket class. Only the 'client'
1688 functions are available. See the Lua Socket documentation:
1689
1690 `http://w3.impa.br/~diego/software/luasocket/tcp.html
1691 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
1692
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001693.. js:function:: Socket.close(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001694
1695 Closes a TCP object. The internal socket used by the object is closed and the
1696 local address to which the object was bound is made available to other
1697 applications. No further operations (except for further calls to the close
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001698 method) are allowed on a closed Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001699
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001700 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001701
1702 Note: It is important to close all used sockets once they are not needed,
1703 since, in many systems, each socket uses a file descriptor, which are limited
1704 system resources. Garbage-collected objects are automatically closed before
1705 destruction, though.
1706
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001707.. js:function:: Socket.connect(socket, address[, port])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001708
1709 Attempts to connect a socket object to a remote host.
1710
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001711
1712 In case of error, the method returns nil followed by a string describing the
1713 error. In case of success, the method returns 1.
1714
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001715 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001716 :param string address: can be an IP address or a host name. See below for more
1717 information.
1718 :param integer port: must be an integer number in the range [1..64K].
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001719 :returns: 1 or nil.
1720
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001721 an address field extension permits to use the connect() function to connect to
1722 other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is
1723 the basically expected format. This format requires the port.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001724
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001725 Other format accepted are a socket path like "/socket/path", it permits to
1726 connect to a socket. abstract namespaces are supported with the prefix
1727 "abns@", and finaly a filedescriotr can be passed with the prefix "fd@".
1728 The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be
1729 passed int the string. The syntax "127.0.0.1:1234" is valid. in this case, the
1730 parameter *port* is ignored.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001731
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001732.. js:function:: Socket.connect_ssl(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001733
1734 Same behavior than the function socket:connect, but uses SSL.
1735
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001736 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001737 :returns: 1 or nil.
1738
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001739.. js:function:: Socket.getpeername(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001740
1741 Returns information about the remote side of a connected client object.
1742
1743 Returns a string with the IP address of the peer, followed by the port number
1744 that peer is using for the connection. In case of error, the method returns
1745 nil.
1746
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001747 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001748 :returns: a string containing the server information.
1749
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001750.. js:function:: Socket.getsockname(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001751
1752 Returns the local address information associated to the object.
1753
1754 The method returns a string with local IP address and a number with the port.
1755 In case of error, the method returns nil.
1756
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001757 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001758 :returns: a string containing the client information.
1759
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001760.. js:function:: Socket.receive(socket, [pattern [, prefix]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001761
1762 Reads data from a client object, according to the specified read pattern.
1763 Patterns follow the Lua file I/O format, and the difference in performance
1764 between all patterns is negligible.
1765
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001766 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001767 :param string|integer pattern: Describe what is required (see below).
1768 :param string prefix: A string which will be prefix the returned data.
1769 :returns: a string containing the required data or nil.
1770
1771 Pattern can be any of the following:
1772
1773 * **`*a`**: reads from the socket until the connection is closed. No
1774 end-of-line translation is performed;
1775
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001776 * **`*l`**: reads a line of text from the Socket. The line is terminated by a
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001777 LF character (ASCII 10), optionally preceded by a CR character
1778 (ASCII 13). The CR and LF characters are not included in the
1779 returned line. In fact, all CR characters are ignored by the
1780 pattern. This is the default pattern.
1781
1782 * **number**: causes the method to read a specified number of bytes from the
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001783 Socket. Prefix is an optional string to be concatenated to the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001784 beginning of any received data before return.
1785
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001786 * **empty**: If the pattern is left empty, the default option is `*l`.
1787
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001788 If successful, the method returns the received pattern. In case of error, the
1789 method returns nil followed by an error message which can be the string
1790 'closed' in case the connection was closed before the transmission was
1791 completed or the string 'timeout' in case there was a timeout during the
1792 operation. Also, after the error message, the function returns the partial
1793 result of the transmission.
1794
1795 Important note: This function was changed severely. It used to support
1796 multiple patterns (but I have never seen this feature used) and now it
1797 doesn't anymore. Partial results used to be returned in the same way as
1798 successful results. This last feature violated the idea that all functions
1799 should return nil on error. Thus it was changed too.
1800
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001801.. js:function:: Socket.send(socket, data [, start [, end ]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001802
1803 Sends data through client object.
1804
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001805 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001806 :param string data: The data that will be sent.
1807 :param integer start: The start position in the buffer of the data which will
1808 be sent.
1809 :param integer end: The end position in the buffer of the data which will
1810 be sent.
1811 :returns: see below.
1812
1813 Data is the string to be sent. The optional arguments i and j work exactly
1814 like the standard string.sub Lua function to allow the selection of a
1815 substring to be sent.
1816
1817 If successful, the method returns the index of the last byte within [start,
1818 end] that has been sent. Notice that, if start is 1 or absent, this is
1819 effectively the total number of bytes sent. In case of error, the method
1820 returns nil, followed by an error message, followed by the index of the last
1821 byte within [start, end] that has been sent. You might want to try again from
1822 the byte following that. The error message can be 'closed' in case the
1823 connection was closed before the transmission was completed or the string
1824 'timeout' in case there was a timeout during the operation.
1825
1826 Note: Output is not buffered. For small strings, it is always better to
1827 concatenate them in Lua (with the '..' operator) and send the result in one
1828 call instead of calling the method several times.
1829
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001830.. js:function:: Socket.setoption(socket, option [, value])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001831
1832 Just implemented for compatibility, this cal does nothing.
1833
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001834.. js:function:: Socket.settimeout(socket, value [, mode])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001835
1836 Changes the timeout values for the object. All I/O operations are blocking.
1837 That is, any call to the methods send, receive, and accept will block
1838 indefinitely, until the operation completes. The settimeout method defines a
1839 limit on the amount of time the I/O methods can block. When a timeout time
1840 has elapsed, the affected methods give up and fail with an error code.
1841
1842 The amount of time to wait is specified as the value parameter, in seconds.
1843
1844 The timeout modes are bot implemented, the only settable timeout is the
1845 inactivity time waiting for complete the internal buffer send or waiting for
1846 receive data.
1847
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001848 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001849 :param integer value: The timeout value.
1850
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001851.. _map_class:
1852
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001853Map class
1854=========
1855
1856.. js:class:: Map
1857
1858 This class permits to do some lookup in HAProxy maps. The declared maps can
1859 be modified during the runtime throught the HAProxy management socket.
1860
1861.. code-block:: lua
1862
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001863 default = "usa"
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001864
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001865 -- Create and load map
1866 geo = Map.new("geo.map", Map.ip);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001867
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001868 -- Create new fetch that returns the user country
1869 core.register_fetches("country", function(txn)
1870 local src;
1871 local loc;
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001872
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001873 src = txn.f:fhdr("x-forwarded-for");
1874 if (src == nil) then
1875 src = txn.f:src()
1876 if (src == nil) then
1877 return default;
1878 end
1879 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001880
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001881 -- Perform lookup
1882 loc = geo:lookup(src);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001883
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001884 if (loc == nil) then
1885 return default;
1886 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001887
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001888 return loc;
1889 end);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001890
1891.. js:attribute:: Map.int
1892
1893 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1894 samples" ans subchapter "ACL basics" to understand this pattern matching
1895 method.
1896
1897.. js:attribute:: Map.ip
1898
1899 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1900 samples" ans subchapter "ACL basics" to understand this pattern matching
1901 method.
1902
1903.. js:attribute:: Map.str
1904
1905 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1906 samples" ans subchapter "ACL basics" to understand this pattern matching
1907 method.
1908
1909.. js:attribute:: Map.beg
1910
1911 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1912 samples" ans subchapter "ACL basics" to understand this pattern matching
1913 method.
1914
1915.. js:attribute:: Map.sub
1916
1917 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1918 samples" ans subchapter "ACL basics" to understand this pattern matching
1919 method.
1920
1921.. js:attribute:: Map.dir
1922
1923 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1924 samples" ans subchapter "ACL basics" to understand this pattern matching
1925 method.
1926
1927.. js:attribute:: Map.dom
1928
1929 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1930 samples" ans subchapter "ACL basics" to understand this pattern matching
1931 method.
1932
1933.. js:attribute:: Map.end
1934
1935 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1936 samples" ans subchapter "ACL basics" to understand this pattern matching
1937 method.
1938
1939.. js:attribute:: Map.reg
1940
1941 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1942 samples" ans subchapter "ACL basics" to understand this pattern matching
1943 method.
1944
1945
1946.. js:function:: Map.new(file, method)
1947
1948 Creates and load a map.
1949
1950 :param string file: Is the file containing the map.
1951 :param integer method: Is the map pattern matching method. See the attributes
1952 of the Map class.
1953 :returns: a class Map object.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001954 :see: The Map attributes: :js:attr:`Map.int`, :js:attr:`Map.ip`,
1955 :js:attr:`Map.str`, :js:attr:`Map.beg`, :js:attr:`Map.sub`,
1956 :js:attr:`Map.dir`, :js:attr:`Map.dom`, :js:attr:`Map.end` and
1957 :js:attr:`Map.reg`.
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001958
1959.. js:function:: Map.lookup(map, str)
1960
1961 Perform a lookup in a map.
1962
1963 :param class_map map: Is the class Map object.
1964 :param string str: Is the string used as key.
1965 :returns: a string containing the result or nil if no match.
1966
1967.. js:function:: Map.slookup(map, str)
1968
1969 Perform a lookup in a map.
1970
1971 :param class_map map: Is the class Map object.
1972 :param string str: Is the string used as key.
1973 :returns: a string containing the result or empty string if no match.
1974
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001975.. _applethttp_class:
1976
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001977AppletHTTP class
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001978================
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001979
1980.. js:class:: AppletHTTP
1981
1982 This class is used with applets that requires the 'http' mode. The http applet
1983 can be registered with the *core.register_service()* function. They are used
1984 for processing an http request like a server in back of HAProxy.
1985
1986 This is an hello world sample code:
1987
1988.. code-block:: lua
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001989
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001990 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001991 local response = "Hello World !"
1992 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02001993 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001994 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02001995 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001996 applet:send(response)
1997 end)
1998
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001999.. js:attribute:: AppletHTTP.c
2000
2001 :returns: A :ref:`converters_class`
2002
2003 This attribute contains a Converters class object.
2004
2005.. js:attribute:: AppletHTTP.sc
2006
2007 :returns: A :ref:`converters_class`
2008
2009 This attribute contains a Converters class object. The
2010 functions of this object returns always a string.
2011
2012.. js:attribute:: AppletHTTP.f
2013
2014 :returns: A :ref:`fetches_class`
2015
2016 This attribute contains a Fetches class object. Note that the
2017 applet execution place cannot access to a valid HAProxy core HTTP
2018 transaction, so some sample fecthes related to the HTTP dependant
2019 values (hdr, path, ...) are not available.
2020
2021.. js:attribute:: AppletHTTP.sf
2022
2023 :returns: A :ref:`fetches_class`
2024
2025 This attribute contains a Fetches class object. The functions of
2026 this object returns always a string. Note that the applet
2027 execution place cannot access to a valid HAProxy core HTTP
2028 transaction, so some sample fecthes related to the HTTP dependant
2029 values (hdr, path, ...) are not available.
2030
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002031.. js:attribute:: AppletHTTP.method
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002032
2033 :returns: string
2034
2035 The attribute method returns a string containing the HTTP
2036 method.
2037
2038.. js:attribute:: AppletHTTP.version
2039
2040 :returns: string
2041
2042 The attribute version, returns a string containing the HTTP
2043 request version.
2044
2045.. js:attribute:: AppletHTTP.path
2046
2047 :returns: string
2048
2049 The attribute path returns a string containing the HTTP
2050 request path.
2051
2052.. js:attribute:: AppletHTTP.qs
2053
2054 :returns: string
2055
2056 The attribute qs returns a string containing the HTTP
2057 request query string.
2058
2059.. js:attribute:: AppletHTTP.length
2060
2061 :returns: integer
2062
2063 The attribute length returns an integer containing the HTTP
2064 body length.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002065
Thierry FOURNIER841475e2015-12-11 17:10:09 +01002066.. js:attribute:: AppletHTTP.headers
2067
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002068 :returns: array
2069
2070 The attribute headers returns an array containing the HTTP
2071 headers. The header names are always in lower case. As the header name can be
2072 encountered more than once in each request, the value is indexed with 0 as
2073 first index value. The array have this form:
2074
2075.. code-block:: lua
2076
2077 AppletHTTP.headers['<header-name>'][<header-index>] = "<header-value>"
2078
2079 AppletHTTP.headers["host"][0] = "www.test.com"
2080 AppletHTTP.headers["accept"][0] = "audio/basic q=1"
2081 AppletHTTP.headers["accept"][1] = "audio/*, q=0.2"
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002082 AppletHTTP.headers["accept"][2] = "*/*, q=0.1"
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002083..
2084
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002085.. js:function:: AppletHTTP.set_status(applet, code [, reason])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002086
2087 This function sets the HTTP status code for the response. The allowed code are
2088 from 100 to 599.
2089
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002090 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002091 :param integer code: the status code returned to the client.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002092 :param string reason: the status reason returned to the client (optional).
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002093
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002094.. js:function:: AppletHTTP.add_header(applet, name, value)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002095
2096 This function add an header in the response. Duplicated headers are not
2097 collapsed. The special header *content-length* is used to determinate the
2098 response length. If it not exists, a *transfer-encoding: chunked* is set, and
2099 all the write from the funcion *AppletHTTP:send()* become a chunk.
2100
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002101 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002102 :param string name: the header name
2103 :param string value: the header value
2104
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002105.. js:function:: AppletHTTP.start_response(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002106
2107 This function indicates to the HTTP engine that it can process and send the
2108 response headers. After this called we cannot add headers to the response; We
2109 cannot use the *AppletHTTP:send()* function if the
2110 *AppletHTTP:start_response()* is not called.
2111
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002112 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2113
2114.. js:function:: AppletHTTP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002115
2116 This function returns a string containing one line from the http body. If the
2117 data returned doesn't contains a final '\\n' its assumed than its the last
2118 available data before the end of stream.
2119
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002120 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002121 :returns: a string. The string can be empty if we reach the end of the stream.
2122
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002123.. js:function:: AppletHTTP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002124
2125 Reads data from the HTTP body, according to the specified read *size*. If the
2126 *size* is missing, the function tries to read all the content of the stream
2127 until the end. If the *size* is bigger than the http body, it returns the
2128 amount of data avalaible.
2129
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002130 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002131 :param integer size: the required read size.
2132 :returns: always return a string,the string can be empty is the connexion is
2133 closed.
2134
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002135.. js:function:: AppletHTTP.send(applet, msg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002136
2137 Send the message *msg* on the http request body.
2138
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002139 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002140 :param string msg: the message to send.
2141
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002142.. js:function:: AppletHTTP.get_priv(applet)
2143
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002144 Return Lua data stored in the current transaction. If no data are stored,
2145 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002146
2147 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2148 :returns: the opaque data previsously stored, or nil if nothing is
2149 avalaible.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002150 :see: :js:func:`AppletHTTP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002151
2152.. js:function:: AppletHTTP.set_priv(applet, data)
2153
2154 Store any data in the current HAProxy transaction. This action replace the
2155 old stored data.
2156
2157 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2158 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002159 :see: :js:func:`AppletHTTP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002160
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002161.. js:function:: AppletHTTP.set_var(applet, var, value)
2162
2163 Converts a Lua type in a HAProxy type and store it in a variable <var>.
2164
2165 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2166 :param string var: The variable name according with the HAProxy variable syntax.
2167 :param type value: The value associated to the variable. The type ca be string or
2168 integer.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002169 :see: :js:func:`AppletHTTP.unset_var`
2170 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002171
2172.. js:function:: AppletHTTP.unset_var(applet, var)
2173
2174 Unset the variable <var>.
2175
2176 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2177 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002178 :see: :js:func:`AppletHTTP.set_var`
2179 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002180
2181.. js:function:: AppletHTTP.get_var(applet, var)
2182
2183 Returns data stored in the variable <var> converter in Lua type.
2184
2185 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2186 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002187 :see: :js:func:`AppletHTTP.set_var`
2188 :see: :js:func:`AppletHTTP.unset_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002189
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002190.. _applettcp_class:
2191
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002192AppletTCP class
2193===============
2194
2195.. js:class:: AppletTCP
2196
2197 This class is used with applets that requires the 'tcp' mode. The tcp applet
2198 can be registered with the *core.register_service()* function. They are used
2199 for processing a tcp stream like a server in back of HAProxy.
2200
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002201.. js:attribute:: AppletTCP.c
2202
2203 :returns: A :ref:`converters_class`
2204
2205 This attribute contains a Converters class object.
2206
2207.. js:attribute:: AppletTCP.sc
2208
2209 :returns: A :ref:`converters_class`
2210
2211 This attribute contains a Converters class object. The
2212 functions of this object returns always a string.
2213
2214.. js:attribute:: AppletTCP.f
2215
2216 :returns: A :ref:`fetches_class`
2217
2218 This attribute contains a Fetches class object.
2219
2220.. js:attribute:: AppletTCP.sf
2221
2222 :returns: A :ref:`fetches_class`
2223
2224 This attribute contains a Fetches class object.
2225
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002226.. js:function:: AppletTCP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002227
2228 This function returns a string containing one line from the stream. If the
2229 data returned doesn't contains a final '\\n' its assumed than its the last
2230 available data before the end of stream.
2231
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002232 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002233 :returns: a string. The string can be empty if we reach the end of the stream.
2234
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002235.. js:function:: AppletTCP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002236
2237 Reads data from the TCP stream, according to the specified read *size*. If the
2238 *size* is missing, the function tries to read all the content of the stream
2239 until the end.
2240
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002241 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002242 :param integer size: the required read size.
2243 :returns: always return a string,the string can be empty is the connexion is
2244 closed.
2245
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002246.. js:function:: AppletTCP.send(appletmsg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002247
2248 Send the message on the stream.
2249
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002250 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002251 :param string msg: the message to send.
2252
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002253.. js:function:: AppletTCP.get_priv(applet)
2254
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002255 Return Lua data stored in the current transaction. If no data are stored,
2256 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002257
2258 :param class_AppletTCP applet: An :ref:`applettcp_class`
2259 :returns: the opaque data previsously stored, or nil if nothing is
2260 avalaible.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002261 :see: :js:func:`AppletTCP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002262
2263.. js:function:: AppletTCP.set_priv(applet, data)
2264
2265 Store any data in the current HAProxy transaction. This action replace the
2266 old stored data.
2267
2268 :param class_AppletTCP applet: An :ref:`applettcp_class`
2269 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002270 :see: :js:func:`AppletTCP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002271
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002272.. js:function:: AppletTCP.set_var(applet, var, value)
2273
2274 Converts a Lua type in a HAProxy type and stores it in a variable <var>.
2275
2276 :param class_AppletTCP applet: An :ref:`applettcp_class`
2277 :param string var: The variable name according with the HAProxy variable syntax.
2278 :param type value: The value associated to the variable. The type can be string or
2279 integer.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002280 :see: :js:func:`AppletTCP.unset_var`
2281 :see: :js:func:`AppletTCP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002282
2283.. js:function:: AppletTCP.unset_var(applet, var)
2284
2285 Unsets the variable <var>.
2286
2287 :param class_AppletTCP applet: An :ref:`applettcp_class`
2288 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002289 :see: :js:func:`AppletTCP.unset_var`
2290 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002291
2292.. js:function:: AppletTCP.get_var(applet, var)
2293
2294 Returns data stored in the variable <var> converter in Lua type.
2295
2296 :param class_AppletTCP applet: An :ref:`applettcp_class`
2297 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002298 :see: :js:func:`AppletTCP.unset_var`
2299 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002300
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002301External Lua libraries
2302======================
2303
2304A lot of useful lua libraries can be found here:
2305
2306* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_
2307
2308Redis acces:
2309
2310* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
2311
2312This is an example about the usage of the Redis library with HAProxy. Note that
2313each call of any function of this library can throw an error if the socket
2314connection fails.
2315
2316.. code-block:: lua
2317
2318 -- load the redis library
2319 local redis = require("redis");
2320
2321 function do_something(txn)
2322
2323 -- create and connect new tcp socket
2324 local tcp = core.tcp();
2325 tcp:settimeout(1);
2326 tcp:connect("127.0.0.1", 6379);
2327
2328 -- use the redis library with this new socket
2329 local client = redis.connect({socket=tcp});
2330 client:ping();
2331
2332 end
2333
2334OpenSSL:
2335
2336* `http://mkottman.github.io/luacrypto/index.html
2337 <http://mkottman.github.io/luacrypto/index.html>`_
2338
2339* `https://github.com/brunoos/luasec/wiki
2340 <https://github.com/brunoos/luasec/wiki>`_
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01002341