blob: 60c972507ad04579c02564db3706d66f5cff4161 [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
122 This attribute is an integer, it contains the value of the loglevel "emergency" (0).
123
124.. js:attribute:: core.alert
125
126 This attribute is an integer, it contains the value of the loglevel "alert" (1).
127
128.. js:attribute:: core.crit
129
130 This attribute is an integer, it contains the value of the loglevel "critical" (2).
131
132.. js:attribute:: core.err
133
134 This attribute is an integer, it contains the value of the loglevel "error" (3).
135
136.. js:attribute:: core.warning
137
138 This attribute is an integer, it contains the value of the loglevel "warning" (4).
139
140.. js:attribute:: core.notice
141
142 This attribute is an integer, it contains the value of the loglevel "notice" (5).
143
144.. js:attribute:: core.info
145
146 This attribute is an integer, it contains the value of the loglevel "info" (6).
147
148.. js:attribute:: core.debug
149
150 This attribute is an integer, it contains the value of the loglevel "debug" (7).
151
152.. js:function:: core.log(loglevel, msg)
153
154 **context**: body, init, task, action, sample-fetch, converter
155
David Carlier61fdf8b2015-10-02 11:59:38 +0100156 This function sends a log. The log is sent, according with the HAProxy
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100157 configuration file, on the default syslog server if it is configured and on
158 the stderr if it is allowed.
159
160 :param integer loglevel: Is the log level asociated with the message. It is a
161 number between 0 and 7.
162 :param string msg: The log content.
163 :see: core.emerg, core.alert, core.crit, core.err, core.warning, core.notice,
164 core.info, core.debug (log level definitions)
165 :see: code.Debug
166 :see: core.Info
167 :see: core.Warning
168 :see: core.Alert
169
170.. js:function:: core.Debug(msg)
171
172 **context**: body, init, task, action, sample-fetch, converter
173
174 :param string msg: The log content.
175 :see: log
176
177 Does the same job than:
178
179.. code-block:: lua
180
181 function Debug(msg)
182 core.log(core.debug, msg)
183 end
184..
185
186.. js:function:: core.Info(msg)
187
188 **context**: body, init, task, action, sample-fetch, converter
189
190 :param string msg: The log content.
191 :see: log
192
193.. code-block:: lua
194
195 function Info(msg)
196 core.log(core.info, msg)
197 end
198..
199
200.. js:function:: core.Warning(msg)
201
202 **context**: body, init, task, action, sample-fetch, converter
203
204 :param string msg: The log content.
205 :see: log
206
207.. code-block:: lua
208
209 function Warning(msg)
210 core.log(core.warning, msg)
211 end
212..
213
214.. js:function:: core.Alert(msg)
215
216 **context**: body, init, task, action, sample-fetch, converter
217
218 :param string msg: The log content.
219 :see: log
220
221.. code-block:: lua
222
223 function Alert(msg)
224 core.log(core.alert, msg)
225 end
226..
227
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100228.. js:function:: core.add_acl(filename, key)
229
230 **context**: init, task, action, sample-fetch, converter
231
232 Add the ACL *key* in the ACLs list referenced by the file *filename*.
233
234 :param string filename: the filename that reference the ACL entries.
235 :param string key: the key which will be added.
236
237.. js:function:: core.del_acl(filename, key)
238
239 **context**: init, task, action, sample-fetch, converter
240
241 Delete the ACL entry referenced by the key *key* in the list of ACLs
242 referenced by *filename*.
243
244 :param string filename: the filename that reference the ACL entries.
245 :param string key: the key which will be deleted.
246
247.. js:function:: core.del_map(filename, key)
248
249 **context**: init, task, action, sample-fetch, converter
250
251 Delete the map entry indexed with the specified key in the list of maps
252 referenced by his filename.
253
254 :param string filename: the filename that reference the map entries.
255 :param string key: the key which will be deleted.
256
257.. js:function:: core.msleep(milliseconds)
258
259 **context**: body, init, task, action
260
261 The `core.msleep()` stops the Lua execution between specified milliseconds.
262
263 :param integer milliseconds: the required milliseconds.
264
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200265.. js:function:: core.register_action(name, actions, func)
266
267 **context**: body
268
David Carlier61fdf8b2015-10-02 11:59:38 +0100269 Register a Lua function executed as action. All the registered action can be
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200270 used in HAProxy with the prefix "lua.". An action gets a TXN object class as
271 input.
272
273 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200274 :param table actions: is a table of string describing the HAProxy actions who
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200275 want to register to. The expected actions are 'tcp-req',
276 'tcp-res', 'http-req' or 'http-res'.
277 :param function func: is the Lua function called to work as converter.
278
279 The prototype of the Lua function used as argument is:
280
281.. code-block:: lua
282
283 function(txn)
284..
285
286 * **txn** (*class TXN*): this is a TXN object used for manipulating the
287 current request or TCP stream.
288
Willy Tarreau61add3c2015-09-28 15:39:10 +0200289 Here, an exemple of action registration. the action juste send an 'Hello world'
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200290 in the logs.
291
292.. code-block:: lua
293
294 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
295 txn:Info("Hello world")
296 end)
297..
298
299 This example code is used in HAproxy configuration like this:
300
301::
302
303 frontend tcp_frt
304 mode tcp
305 tcp-request content lua.hello-world
306
307 frontend http_frt
308 mode http
309 http-request lua.hello-world
310
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100311.. js:function:: core.register_converters(name, func)
312
313 **context**: body
314
David Carlier61fdf8b2015-10-02 11:59:38 +0100315 Register a Lua function executed as converter. All the registered converters
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100316 can be used in HAProxy with the prefix "lua.". An converter get a string as
317 input and return a string as output. The registered function can take up to 9
318 values as parameter. All the value are strings.
319
320 :param string name: is the name of the converter.
321 :param function func: is the Lua function called to work as converter.
322
323 The prototype of the Lua function used as argument is:
324
325.. code-block:: lua
326
327 function(str, [p1 [, p2 [, ... [, p5]]]])
328..
329
330 * **str** (*string*): this is the input value automatically converted in
331 string.
332 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
333 the haroxy configuration file. The number of arguments doesn't exceed 5.
334 The order and the nature of these is conventionally choose by the
335 developper.
336
337.. js:function:: core.register_fetches(name, func)
338
339 **context**: body
340
David Carlier61fdf8b2015-10-02 11:59:38 +0100341 Register a Lua function executed as sample fetch. All the registered sample
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100342 fetchs can be used in HAProxy with the prefix "lua.". A Lua sample fetch
343 return a string as output. The registered function can take up to 9 values as
344 parameter. All the value are strings.
345
346 :param string name: is the name of the converter.
347 :param function func: is the Lua function called to work as sample fetch.
348
349 The prototype of the Lua function used as argument is:
350
351.. code-block:: lua
352
353 string function(txn, [p1 [, p2 [, ... [, p5]]]])
354..
355
356 * **txn** (*class txn*): this is the txn object associated with the current
357 request.
358 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
359 the haroxy configuration file. The number of arguments doesn't exceed 5.
360 The order and the nature of these is conventionally choose by the
361 developper.
362 * **Returns**: A string containing some data, ot nil if the value cannot be
363 returned now.
364
365 lua example code:
366
367.. code-block:: lua
368
369 core.register_fetches("hello", function(txn)
370 return "hello"
371 end)
372..
373
374 HAProxy example configuration:
375
376::
377
378 frontend example
379 http-request redirect location /%[lua.hello]
380
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200381.. js:function:: core.register_service(name, mode, func)
382
383 **context**: body
384
David Carlier61fdf8b2015-10-02 11:59:38 +0100385 Register a Lua function executed as a service. All the registered service can
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200386 be used in HAProxy with the prefix "lua.". A service gets an object class as
387 input according with the required mode.
388
389 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200390 :param string mode: is string describing the required mode. Only 'tcp' or
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200391 'http' are allowed.
392 :param function func: is the Lua function called to work as converter.
393
394 The prototype of the Lua function used as argument is:
395
396.. code-block:: lua
397
398 function(applet)
399..
400
401 * **txn** (*class AppletTCP*) or (*class AppletHTTP*): this is an object used
402 for manipulating the current HTTP request or TCP stream.
403
Willy Tarreau61add3c2015-09-28 15:39:10 +0200404 Here, an exemple of service registration. the service just send an 'Hello world'
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200405 as an http response.
406
407.. code-block:: lua
408
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100409 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200410 local response = "Hello World !"
411 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200412 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200413 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200414 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200415 applet:send(response)
416 end)
417..
418
419 This example code is used in HAproxy configuration like this:
420
421::
422
423 frontend example
424 http-request use-service lua.hello-world
425
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100426.. js:function:: core.register_init(func)
427
428 **context**: body
429
430 Register a function executed after the configuration parsing. This is useful
431 to check any parameters.
432
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100433 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100434
435 The prototype of the Lua function used as argument is:
436
437.. code-block:: lua
438
439 function()
440..
441
442 It takes no input, and no output is expected.
443
444.. js:function:: core.register_task(func)
445
446 **context**: body, init, task, action, sample-fetch, converter
447
448 Register and start independent task. The task is started when the HAProxy
449 main scheduler starts. For example this type of tasks can be executed to
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100450 perform complex health checks.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100451
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100452 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100453
454 The prototype of the Lua function used as argument is:
455
456.. code-block:: lua
457
458 function()
459..
460
461 It takes no input, and no output is expected.
462
463.. js:function:: core.set_nice(nice)
464
465 **context**: task, action, sample-fetch, converter
466
467 Change the nice of the current task or current session.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100468
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100469 :param integer nice: the nice value, it must be between -1024 and 1024.
470
471.. js:function:: core.set_map(filename, key, value)
472
473 **context**: init, task, action, sample-fetch, converter
474
475 set the value *value* associated to the key *key* in the map referenced by
476 *filename*.
477
478.. js:function:: core.sleep(int seconds)
479
480 **context**: body, init, task, action
481
482 The `core.sleep()` functions stop the Lua execution between specified seconds.
483
484 :param integer seconds: the required seconds.
485
486.. js:function:: core.tcp()
487
488 **context**: init, task, action
489
490 This function returns a new object of a *socket* class.
491
492 :returns: A socket class object.
493
Thierry FOURNIER0a99b892015-08-26 00:14:17 +0200494.. js:function:: core.done(data)
495
496 **context**: body, init, task, action, sample-fetch, converter
497
498 :param any data: Return some data for the caller. It is useful with
499 sample-fetches and sample-converters.
500
501 Immediately stops the current Lua execution and returns to the caller which
502 may be a sample fetch, a converter or an action and returns the specified
503 value (ignored for actions). It is used when the LUA process finishes its
504 work and wants to give back the control to HAProxy without executing the
505 remaining code. It can be seen as a multi-level "return".
506
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100507.. js:function:: core.yield()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100508
509 **context**: task, action, sample-fetch, converter
510
511 Give back the hand at the HAProxy scheduler. It is used when the LUA
512 processing consumes a lot of processing time.
513
514Fetches class
515=============
516
517.. js:class:: Fetches
518
519 This class contains a lot of internal HAProxy sample fetches. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100520 HAProxy "configuration.txt" documentation for more information about her
521 usage. they are the chapters 7.3.2 to 7.3.6.
522
523 :see: TXN.f
524 :see: TXN.sf
525
526 Fetches are useful for:
527
528 * get system time,
529 * get environment variable,
530 * get random numbers,
531 * known backend status like the number of users in queue or the number of
532 connections established,
533 * client information like ip source or destination,
534 * deal with stick tables,
535 * Established SSL informations,
536 * HTTP information like headers or method.
537
538.. code-block:: lua
539
540 function action(txn)
541 -- Get source IP
542 local clientip = txn.f:src()
543 end
544..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100545
546Converters class
547================
548
549.. js:class:: Converters
550
551 This class contains a lot of internal HAProxy sample converters. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100552 HAProxy documentation "configuration.txt" for more information about her
553 usage. Its the chapter 7.3.1.
554
555 :see: TXN.c
556 :see: TXN.sc
557
558 Converters provides statefull transformation. They are useful for:
559
560 * converting input to base64,
561 * applying hash on input string (djb2, crc32, sdbm, wt6),
562 * format date,
563 * json escape,
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100564 * extracting preferred language comparing two lists,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100565 * turn to lower or upper chars,
566 * deal with stick tables.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100567
568Channel class
569=============
570
571.. js:class:: Channel
572
573 HAProxy uses two buffers for the processing of the requests. The first one is
574 used with the request data (from the client to the server) and the second is
575 used for the response data (from the server to the client).
576
577 Each buffer contains two types of data. The first type is the incoming data
578 waiting for a processing. The second part is the outgoing data already
579 processed. Usually, the incoming data is processed, after it is tagged as
580 outgoing data, and finally it is sent. The following functions provides tools
581 for manipulating these data in a buffer.
582
583 The following diagram shows where the channel class function are applied.
584
585 **Warning**: It is not possible to read from the response in request action,
586 and it is not possible to read for the request channel in response action.
587
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100588.. image:: _static/channel.png
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100589
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100590.. js:function:: Channel.dup(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100591
592 This function returns a string that contain the entire buffer. The data is
593 not remove from the buffer and can be reprocessed later.
594
595 If the buffer cant receive more data, a 'nil' value is returned.
596
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100597 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100598 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100599
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100600.. js:function:: Channel.get(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100601
602 This function returns a string that contain the entire buffer. The data is
603 consumed from the buffer.
604
605 If the buffer cant receive more data, a 'nil' value is returned.
606
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100607 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100608 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100609
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200610.. js:function:: Channel.getline(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100611
612 This function returns a string that contain the first line of the buffer. The
613 data is consumed. If the data returned doesn't contains a final '\n' its
614 assumed than its the last available data in the buffer.
615
616 If the buffer cant receive more data, a 'nil' value is returned.
617
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100618 :param class_channel channel: The manipulated Channel.
Pieter Baauw386a1272015-08-16 15:26:24 +0200619 :returns: a string containing the available line or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100620
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100621.. js:function:: Channel.set(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100622
623 This function replace the content of the buffer by the string. The function
624 returns the copied length, otherwise, it returns -1.
625
626 The data set with this function are not send. They wait for the end of
627 HAProxy processing, so the buffer can be full.
628
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100629 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100630 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100631 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100632
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100633.. js:function:: Channel.append(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100634
635 This function append the string argument to the content of the buffer. The
636 function returns the copied length, otherwise, it returns -1.
637
638 The data set with this function are not send. They wait for the end of
639 HAProxy processing, so the buffer can be full.
640
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100641 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100642 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100643 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100644
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100645.. js:function:: Channel.send(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100646
647 This function required immediate send of the data. Unless if the connection
648 is close, the buffer is regularly flushed and all the string can be sent.
649
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100650 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100651 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100652 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100653
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100654.. js:function:: Channel.get_in_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100655
656 This function returns the length of the input part of the buffer.
657
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100658 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100659 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100660
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100661.. js:function:: Channel.get_out_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100662
663 This function returns the length of the output part of the buffer.
664
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100665 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100666 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100667
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100668.. js:function:: Channel.forward(channel, int)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100669
670 This function transfer bytes from the input part of the buffer to the output
671 part.
672
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100673 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100674 :param integer int: The amount of data which will be forwarded.
675
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100676
677HTTP class
678==========
679
680.. js:class:: HTTP
681
682 This class contain all the HTTP manipulation functions.
683
Pieter Baauw386a1272015-08-16 15:26:24 +0200684.. js:function:: HTTP.req_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100685
686 Returns an array containing all the request headers.
687
688 :param class_http http: The related http object.
689 :returns: array of headers.
Pieter Baauw386a1272015-08-16 15:26:24 +0200690 :see: HTTP.res_get_headers()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100691
Pieter Baauw386a1272015-08-16 15:26:24 +0200692.. js:function:: HTTP.res_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100693
694 Returns an array containing all the response headers.
695
696 :param class_http http: The related http object.
697 :returns: array of headers.
Pieter Baauw386a1272015-08-16 15:26:24 +0200698 :see: HTTP.req_get_headers()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100699
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100700.. js:function:: HTTP.req_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100701
702 Appends an HTTP header field in the request whose name is
703 specified in "name" and whose value is defined in "value".
704
705 :param class_http http: The related http object.
706 :param string name: The header name.
707 :param string value: The header value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100708 :see: HTTP.res_add_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100709
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100710.. js:function:: HTTP.res_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100711
712 appends an HTTP header field in the response whose name is
713 specified in "name" and whose value is defined in "value".
714
715 :param class_http http: The related http object.
716 :param string name: The header name.
717 :param string value: The header value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100718 :see: HTTP.req_add_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100719
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100720.. js:function:: HTTP.req_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100721
722 Removes all HTTP header fields in the request whose name is
723 specified in "name".
724
725 :param class_http http: The related http object.
726 :param string name: The header name.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100727 :see: HTTP.res_del_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100728
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100729.. js:function:: HTTP.res_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100730
731 Removes all HTTP header fields in the response whose name is
732 specified in "name".
733
734 :param class_http http: The related http object.
735 :param string name: The header name.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100736 :see: HTTP.req_del_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100737
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100738.. js:function:: HTTP.req_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100739
740 This variable replace all occurence of all header "name", by only
741 one containing the "value".
742
743 :param class_http http: The related http object.
744 :param string name: The header name.
745 :param string value: The header value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100746 :see: HTTP.res_set_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100747
748 This function does the same work as the folowwing code:
749
750.. code-block:: lua
751
752 function fcn(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100753 TXN.http:req_del_header("header")
754 TXN.http:req_add_header("header", "value")
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100755 end
756..
757
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100758.. js:function:: HTTP.res_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100759
760 This variable replace all occurence of all header "name", by only
761 one containing the "value".
762
763 :param class_http http: The related http object.
764 :param string name: The header name.
765 :param string value: The header value.
Pieter Baauw386a1272015-08-16 15:26:24 +0200766 :see: HTTP.req_rep_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100767
Pieter Baauw386a1272015-08-16 15:26:24 +0200768.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100769
770 Matches the regular expression in all occurrences of header field "name"
771 according to "regex", and replaces them with the "replace" argument. The
772 replacement value can contain back references like \1, \2, ... This
773 function works with the request.
774
775 :param class_http http: The related http object.
776 :param string name: The header name.
777 :param string regex: The match regular expression.
778 :param string replace: The replacement value.
Pieter Baauw386a1272015-08-16 15:26:24 +0200779 :see: HTTP.res_rep_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100780
Pieter Baauw386a1272015-08-16 15:26:24 +0200781.. js:function:: HTTP.res_rep_header(http, name, regex, string)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100782
783 Matches the regular expression in all occurrences of header field "name"
784 according to "regex", and replaces them with the "replace" argument. The
785 replacement value can contain back references like \1, \2, ... This
786 function works with the request.
787
788 :param class_http http: The related http object.
789 :param string name: The header name.
790 :param string regex: The match regular expression.
791 :param string replace: The replacement value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100792 :see: HTTP.req_replace_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100793
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100794.. js:function:: HTTP.req_replace_value(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100795
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100796 Works like "HTTP.req_replace_header()" except that it matches the regex
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100797 against every comma-delimited value of the header field "name" instead of the
798 entire header.
799
800 :param class_http http: The related http object.
801 :param string name: The header name.
802 :param string regex: The match regular expression.
803 :param string replace: The replacement value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100804 :see: HTTP.req_replace_header()
805 :see: HTTP.res_replace_value()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100806
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100807.. js:function:: HTTP.res_replace_value(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100808
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100809 Works like "HTTP.res_replace_header()" except that it matches the regex
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100810 against every comma-delimited value of the header field "name" instead of the
811 entire header.
812
813 :param class_http http: The related http object.
814 :param string name: The header name.
815 :param string regex: The match regular expression.
816 :param string replace: The replacement value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100817 :see: HTTP.res_replace_header()
818 :see: HTTP.req_replace_value()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100819
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100820.. js:function:: HTTP.req_set_method(http, method)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100821
822 Rewrites the request method with the parameter "method".
823
824 :param class_http http: The related http object.
825 :param string method: The new method.
826
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100827.. js:function:: HTTP.req_set_path(http, path)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100828
829 Rewrites the request path with the "path" parameter.
830
831 :param class_http http: The related http object.
832 :param string path: The new path.
833
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100834.. js:function:: HTTP.req_set_query(http, query)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100835
836 Rewrites the request's query string which appears after the first question
837 mark ("?") with the parameter "query".
838
839 :param class_http http: The related http object.
840 :param string query: The new query.
841
Thierry FOURNIER0d79cf62015-08-26 14:20:58 +0200842.. js:function:: HTTP.req_set_uri(http, uri)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100843
844 Rewrites the request URI with the parameter "uri".
845
846 :param class_http http: The related http object.
847 :param string uri: The new uri.
848
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +0200849.. js:function:: HTTP.res_set_status(http, status)
850
851 Rewrites the response status code with the parameter "code". Note that the
852 reason is automatically adapted to the new code.
853
854 :param class_http http: The related http object.
855 :param integer status: The new response status code.
856
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100857TXN class
858=========
859
860.. js:class:: TXN
861
862 The txn class contain all the functions relative to the http or tcp
863 transaction (Note than a tcp stream is the same than a tcp transaction, but
864 an HTTP transaction is not the same than a tcp stream).
865
866 The usage of this class permits to retrieve data from the requests, alter it
867 and forward it.
868
869 All the functions provided by this class are available in the context
870 **sample-fetches** and **actions**.
871
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100872.. js:attribute:: TXN.c
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100873
874 This attribute contains a Converters class object.
875
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100876.. js:attribute:: TXN.sc
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100877
878 This attribute contains a Converters class object. The functions of
879 this object returns always a string.
880
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100881.. js:attribute:: TXN.f
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100882
883 This attribute contains a Fetches class object.
884
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100885.. js:attribute:: TXN.sf
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100886
887 This attribute contains a Fetches class object. The functions of
888 this object returns always a string.
889
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100890.. js:attribute:: TXN.req
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100891
892 This attribute contains a channel class object for the request buffer.
893
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100894.. js:attribute:: TXN.res
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100895
896 This attribute contains a channel class object for the response buffer.
897
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100898.. js:attribute:: TXN.http
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100899
900 This attribute contains an HTTP class object. It is avalaible only if the
901 proxy has the "mode http" enabled.
902
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100903.. js:function:: TXN.log(TXN, loglevel, msg)
904
905 This function sends a log. The log is sent, according with the HAProxy
906 configuration file, on the default syslog server if it is configured and on
907 the stderr if it is allowed.
908
909 :param class_txn txn: The class txn object containing the data.
910 :param integer loglevel: Is the log level asociated with the message. It is a
911 number between 0 and 7.
912 :param string msg: The log content.
913 :see: core.emerg, core.alert, core.crit, core.err, core.warning, core.notice,
914 core.info, core.debug (log level definitions)
915 :see: TXN.deflog
916 :see: TXN.Debug
917 :see: TXN.Info
918 :see: TXN.Warning
919 :see: TXN.Alert
920
921.. js:function:: TXN.deflog(TXN, msg)
922
923 Sends a log line with the default loglevel for the proxy ssociated with the
924 transaction.
925
926 :param class_txn txn: The class txn object containing the data.
927 :param string msg: The log content.
928 :see: TXN.log
929
930.. js:function:: TXN.Debug(txn, msg)
931
932 :param class_txn txn: The class txn object containing the data.
933 :param string msg: The log content.
934 :see: TXN.log
935
936 Does the same job than:
937
938.. code-block:: lua
939
940 function Debug(txn, msg)
941 TXN.log(txn, core.debug, msg)
942 end
943..
944
945.. js:function:: TXN.Info(txn, msg)
946
947 :param class_txn txn: The class txn object containing the data.
948 :param string msg: The log content.
949 :see: TXN.log
950
951.. code-block:: lua
952
953 function Debug(txn, msg)
954 TXN.log(txn, core.info, msg)
955 end
956..
957
958.. js:function:: TXN.Warning(txn, msg)
959
960 :param class_txn txn: The class txn object containing the data.
961 :param string msg: The log content.
962 :see: TXN.log
963
964.. code-block:: lua
965
966 function Debug(txn, msg)
967 TXN.log(txn, core.warning, msg)
968 end
969..
970
971.. js:function:: TXN.Alert(txn, msg)
972
973 :param class_txn txn: The class txn object containing the data.
974 :param string msg: The log content.
975 :see: TXN.log
976
977.. code-block:: lua
978
979 function Debug(txn, msg)
980 TXN.log(txn, core.alert, msg)
981 end
982..
983
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100984.. js:function:: TXN.get_priv(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100985
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100986 Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100987 function. If no data are stored, it returns a nil value.
988
989 :param class_txn txn: The class txn object containing the data.
990 :returns: the opaque data previsously stored, or nil if nothing is
991 avalaible.
992
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100993.. js:function:: TXN.set_priv(txn, data)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100994
995 Store any data in the current HAProxy transaction. This action replace the
996 old stored data.
997
998 :param class_txn txn: The class txn object containing the data.
999 :param opaque data: The data which is stored in the transaction.
1000
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001001.. js:function:: TXN.set_var(TXN, var, value)
1002
David Carlier61fdf8b2015-10-02 11:59:38 +01001003 Converts a Lua type in a HAProxy type and store it in a variable <var>.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001004
1005 :param class_txn txn: The class txn object containing the data.
1006 :param string var: The variable name according with the HAProxy variable syntax.
1007 :param opaque value: The data which is stored in the variable.
1008
1009.. js:function:: TXN.get_var(TXN, var)
1010
1011 Returns data stored in the variable <var> converter in Lua type.
1012
1013 :param class_txn txn: The class txn object containing the data.
1014 :param string var: The variable name according with the HAProxy variable syntax.
1015
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001016.. js:function:: TXN.get_headers(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001017
1018 This function returns an array of headers.
1019
1020 :param class_txn txn: The class txn object containing the data.
1021 :returns: an array of headers.
1022
Willy Tarreaubc183a62015-08-28 10:39:11 +02001023.. js:function:: TXN.done(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001024
Willy Tarreaubc183a62015-08-28 10:39:11 +02001025 This function terminates processing of the transaction and the associated
1026 session. It can be used when a critical error is detected or to terminate
1027 processing after some data have been returned to the client (eg: a redirect).
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001028
1029 :param class_txn txn: The class txn object containing the data.
1030
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001031
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001032
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001033
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001034
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001035
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001036
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001037.. js:function:: TXN.set_loglevel(txn, loglevel)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001038
1039 Is used to change the log level of the current request. The "loglevel" must
1040 be an integer between 0 and 7.
1041
1042 :param class_txn txn: The class txn object containing the data.
1043 :param integer loglevel: The required log level. This variable can be one of
1044 :see: core.<loglevel>
1045
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001046.. js:function:: TXN.set_tos(txn, tos)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001047
1048 Is used to set the TOS or DSCP field value of packets sent to the client to
1049 the value passed in "tos" on platforms which support this.
1050
1051 :param class_txn txn: The class txn object containing the data.
1052 :param integer tos: The new TOS os DSCP.
1053
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001054.. js:function:: TXN.set_mark(txn, mark)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001055
1056 Is used to set the Netfilter MARK on all packets sent to the client to the
1057 value passed in "mark" on platforms which support it.
1058
1059 :param class_txn txn: The class txn object containing the data.
1060 :param integer mark: The mark value.
1061
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001062Socket class
1063============
1064
1065.. js:class:: Socket
1066
1067 This class must be compatible with the Lua Socket class. Only the 'client'
1068 functions are available. See the Lua Socket documentation:
1069
1070 `http://w3.impa.br/~diego/software/luasocket/tcp.html
1071 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
1072
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001073.. js:function:: Socket.close(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001074
1075 Closes a TCP object. The internal socket used by the object is closed and the
1076 local address to which the object was bound is made available to other
1077 applications. No further operations (except for further calls to the close
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001078 method) are allowed on a closed Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001079
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001080 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001081
1082 Note: It is important to close all used sockets once they are not needed,
1083 since, in many systems, each socket uses a file descriptor, which are limited
1084 system resources. Garbage-collected objects are automatically closed before
1085 destruction, though.
1086
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001087.. js:function:: Socket.connect(socket, address[, port])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001088
1089 Attempts to connect a socket object to a remote host.
1090
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001091
1092 In case of error, the method returns nil followed by a string describing the
1093 error. In case of success, the method returns 1.
1094
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001095 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001096 :param string address: can be an IP address or a host name. See below for more
1097 information.
1098 :param integer port: must be an integer number in the range [1..64K].
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001099 :returns: 1 or nil.
1100
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001101 an address field extension permits to use the connect() function to connect to
1102 other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is
1103 the basically expected format. This format requires the port.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001104
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001105 Other format accepted are a socket path like "/socket/path", it permits to
1106 connect to a socket. abstract namespaces are supported with the prefix
1107 "abns@", and finaly a filedescriotr can be passed with the prefix "fd@".
1108 The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be
1109 passed int the string. The syntax "127.0.0.1:1234" is valid. in this case, the
1110 parameter *port* is ignored.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001111
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001112.. js:function:: Socket.connect_ssl(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001113
1114 Same behavior than the function socket:connect, but uses SSL.
1115
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001116 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001117 :returns: 1 or nil.
1118
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001119.. js:function:: Socket.getpeername(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001120
1121 Returns information about the remote side of a connected client object.
1122
1123 Returns a string with the IP address of the peer, followed by the port number
1124 that peer is using for the connection. In case of error, the method returns
1125 nil.
1126
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001127 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001128 :returns: a string containing the server information.
1129
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001130.. js:function:: Socket.getsockname(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001131
1132 Returns the local address information associated to the object.
1133
1134 The method returns a string with local IP address and a number with the port.
1135 In case of error, the method returns nil.
1136
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001137 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001138 :returns: a string containing the client information.
1139
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001140.. js:function:: Socket.receive(socket, [pattern [, prefix]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001141
1142 Reads data from a client object, according to the specified read pattern.
1143 Patterns follow the Lua file I/O format, and the difference in performance
1144 between all patterns is negligible.
1145
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001146 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001147 :param string|integer pattern: Describe what is required (see below).
1148 :param string prefix: A string which will be prefix the returned data.
1149 :returns: a string containing the required data or nil.
1150
1151 Pattern can be any of the following:
1152
1153 * **`*a`**: reads from the socket until the connection is closed. No
1154 end-of-line translation is performed;
1155
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001156 * **`*l`**: reads a line of text from the Socket. The line is terminated by a
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001157 LF character (ASCII 10), optionally preceded by a CR character
1158 (ASCII 13). The CR and LF characters are not included in the
1159 returned line. In fact, all CR characters are ignored by the
1160 pattern. This is the default pattern.
1161
1162 * **number**: causes the method to read a specified number of bytes from the
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001163 Socket. Prefix is an optional string to be concatenated to the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001164 beginning of any received data before return.
1165
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001166 * **empty**: If the pattern is left empty, the default option is `*l`.
1167
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001168 If successful, the method returns the received pattern. In case of error, the
1169 method returns nil followed by an error message which can be the string
1170 'closed' in case the connection was closed before the transmission was
1171 completed or the string 'timeout' in case there was a timeout during the
1172 operation. Also, after the error message, the function returns the partial
1173 result of the transmission.
1174
1175 Important note: This function was changed severely. It used to support
1176 multiple patterns (but I have never seen this feature used) and now it
1177 doesn't anymore. Partial results used to be returned in the same way as
1178 successful results. This last feature violated the idea that all functions
1179 should return nil on error. Thus it was changed too.
1180
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001181.. js:function:: Socket.send(socket, data [, start [, end ]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001182
1183 Sends data through client object.
1184
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001185 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001186 :param string data: The data that will be sent.
1187 :param integer start: The start position in the buffer of the data which will
1188 be sent.
1189 :param integer end: The end position in the buffer of the data which will
1190 be sent.
1191 :returns: see below.
1192
1193 Data is the string to be sent. The optional arguments i and j work exactly
1194 like the standard string.sub Lua function to allow the selection of a
1195 substring to be sent.
1196
1197 If successful, the method returns the index of the last byte within [start,
1198 end] that has been sent. Notice that, if start is 1 or absent, this is
1199 effectively the total number of bytes sent. In case of error, the method
1200 returns nil, followed by an error message, followed by the index of the last
1201 byte within [start, end] that has been sent. You might want to try again from
1202 the byte following that. The error message can be 'closed' in case the
1203 connection was closed before the transmission was completed or the string
1204 'timeout' in case there was a timeout during the operation.
1205
1206 Note: Output is not buffered. For small strings, it is always better to
1207 concatenate them in Lua (with the '..' operator) and send the result in one
1208 call instead of calling the method several times.
1209
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001210.. js:function:: Socket.setoption(socket, option [, value])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001211
1212 Just implemented for compatibility, this cal does nothing.
1213
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001214.. js:function:: Socket.settimeout(socket, value [, mode])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001215
1216 Changes the timeout values for the object. All I/O operations are blocking.
1217 That is, any call to the methods send, receive, and accept will block
1218 indefinitely, until the operation completes. The settimeout method defines a
1219 limit on the amount of time the I/O methods can block. When a timeout time
1220 has elapsed, the affected methods give up and fail with an error code.
1221
1222 The amount of time to wait is specified as the value parameter, in seconds.
1223
1224 The timeout modes are bot implemented, the only settable timeout is the
1225 inactivity time waiting for complete the internal buffer send or waiting for
1226 receive data.
1227
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001228 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001229 :param integer value: The timeout value.
1230
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001231Map class
1232=========
1233
1234.. js:class:: Map
1235
1236 This class permits to do some lookup in HAProxy maps. The declared maps can
1237 be modified during the runtime throught the HAProxy management socket.
1238
1239.. code-block:: lua
1240
1241 default = "usa"
1242
1243 -- Create and load map
1244 geo = Map.new("geo.map", Map.ip);
1245
1246 -- Create new fetch that returns the user country
1247 core.register_fetches("country", function(txn)
1248 local src;
1249 local loc;
1250
1251 src = txn.f:fhdr("x-forwarded-for");
1252 if (src == nil) then
1253 src = txn.f:src()
1254 if (src == nil) then
1255 return default;
1256 end
1257 end
1258
1259 -- Perform lookup
1260 loc = geo:lookup(src);
1261
1262 if (loc == nil) then
1263 return default;
1264 end
1265
1266 return loc;
1267 end);
1268
1269.. js:attribute:: Map.int
1270
1271 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1272 samples" ans subchapter "ACL basics" to understand this pattern matching
1273 method.
1274
1275.. js:attribute:: Map.ip
1276
1277 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1278 samples" ans subchapter "ACL basics" to understand this pattern matching
1279 method.
1280
1281.. js:attribute:: Map.str
1282
1283 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1284 samples" ans subchapter "ACL basics" to understand this pattern matching
1285 method.
1286
1287.. js:attribute:: Map.beg
1288
1289 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1290 samples" ans subchapter "ACL basics" to understand this pattern matching
1291 method.
1292
1293.. js:attribute:: Map.sub
1294
1295 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1296 samples" ans subchapter "ACL basics" to understand this pattern matching
1297 method.
1298
1299.. js:attribute:: Map.dir
1300
1301 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1302 samples" ans subchapter "ACL basics" to understand this pattern matching
1303 method.
1304
1305.. js:attribute:: Map.dom
1306
1307 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1308 samples" ans subchapter "ACL basics" to understand this pattern matching
1309 method.
1310
1311.. js:attribute:: Map.end
1312
1313 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1314 samples" ans subchapter "ACL basics" to understand this pattern matching
1315 method.
1316
1317.. js:attribute:: Map.reg
1318
1319 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1320 samples" ans subchapter "ACL basics" to understand this pattern matching
1321 method.
1322
1323
1324.. js:function:: Map.new(file, method)
1325
1326 Creates and load a map.
1327
1328 :param string file: Is the file containing the map.
1329 :param integer method: Is the map pattern matching method. See the attributes
1330 of the Map class.
1331 :returns: a class Map object.
1332 :see: The Map attributes.
1333
1334.. js:function:: Map.lookup(map, str)
1335
1336 Perform a lookup in a map.
1337
1338 :param class_map map: Is the class Map object.
1339 :param string str: Is the string used as key.
1340 :returns: a string containing the result or nil if no match.
1341
1342.. js:function:: Map.slookup(map, str)
1343
1344 Perform a lookup in a map.
1345
1346 :param class_map map: Is the class Map object.
1347 :param string str: Is the string used as key.
1348 :returns: a string containing the result or empty string if no match.
1349
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001350AppletHTTP class
1351===============
1352
1353.. js:class:: AppletHTTP
1354
1355 This class is used with applets that requires the 'http' mode. The http applet
1356 can be registered with the *core.register_service()* function. They are used
1357 for processing an http request like a server in back of HAProxy.
1358
1359 This is an hello world sample code:
1360
1361.. code-block:: lua
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001362 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001363 local response = "Hello World !"
1364 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02001365 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001366 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02001367 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001368 applet:send(response)
1369 end)
1370
1371
1372.. js:function:: AppletHTTP.set_status(code)
1373
1374 This function sets the HTTP status code for the response. The allowed code are
1375 from 100 to 599.
1376
1377 :param integer code: the status code returned to the client.
1378
1379.. js:function:: AppletHTTP.add_header(name, value)
1380
1381 This function add an header in the response. Duplicated headers are not
1382 collapsed. The special header *content-length* is used to determinate the
1383 response length. If it not exists, a *transfer-encoding: chunked* is set, and
1384 all the write from the funcion *AppletHTTP:send()* become a chunk.
1385
1386 :param string name: the header name
1387 :param string value: the header value
1388
1389.. js:function:: AppletHTTP.start_response()
1390
1391 This function indicates to the HTTP engine that it can process and send the
1392 response headers. After this called we cannot add headers to the response; We
1393 cannot use the *AppletHTTP:send()* function if the
1394 *AppletHTTP:start_response()* is not called.
1395
1396.. js:function:: AppletHTTP.getline()
1397
1398 This function returns a string containing one line from the http body. If the
1399 data returned doesn't contains a final '\\n' its assumed than its the last
1400 available data before the end of stream.
1401
1402 :returns: a string. The string can be empty if we reach the end of the stream.
1403
1404.. js:function:: AppletHTTP.receive([size])
1405
1406 Reads data from the HTTP body, according to the specified read *size*. If the
1407 *size* is missing, the function tries to read all the content of the stream
1408 until the end. If the *size* is bigger than the http body, it returns the
1409 amount of data avalaible.
1410
1411 :param integer size: the required read size.
1412 :returns: always return a string,the string can be empty is the connexion is
1413 closed.
1414
1415.. js:function:: AppletHTTP.send(msg)
1416
1417 Send the message *msg* on the http request body.
1418
1419 :param string msg: the message to send.
1420
1421AppletTCP class
1422===============
1423
1424.. js:class:: AppletTCP
1425
1426 This class is used with applets that requires the 'tcp' mode. The tcp applet
1427 can be registered with the *core.register_service()* function. They are used
1428 for processing a tcp stream like a server in back of HAProxy.
1429
1430.. js:function:: AppletTCP.getline()
1431
1432 This function returns a string containing one line from the stream. If the
1433 data returned doesn't contains a final '\\n' its assumed than its the last
1434 available data before the end of stream.
1435
1436 :returns: a string. The string can be empty if we reach the end of the stream.
1437
1438.. js:function:: AppletTCP.receive([size])
1439
1440 Reads data from the TCP stream, according to the specified read *size*. If the
1441 *size* is missing, the function tries to read all the content of the stream
1442 until the end.
1443
1444 :param integer size: the required read size.
1445 :returns: always return a string,the string can be empty is the connexion is
1446 closed.
1447
1448.. js:function:: AppletTCP.send(msg)
1449
1450 Send the message on the stream.
1451
1452 :param string msg: the message to send.
1453
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001454External Lua libraries
1455======================
1456
1457A lot of useful lua libraries can be found here:
1458
1459* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_
1460
1461Redis acces:
1462
1463* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
1464
1465This is an example about the usage of the Redis library with HAProxy. Note that
1466each call of any function of this library can throw an error if the socket
1467connection fails.
1468
1469.. code-block:: lua
1470
1471 -- load the redis library
1472 local redis = require("redis");
1473
1474 function do_something(txn)
1475
1476 -- create and connect new tcp socket
1477 local tcp = core.tcp();
1478 tcp:settimeout(1);
1479 tcp:connect("127.0.0.1", 6379);
1480
1481 -- use the redis library with this new socket
1482 local client = redis.connect({socket=tcp});
1483 client:ping();
1484
1485 end
1486
1487OpenSSL:
1488
1489* `http://mkottman.github.io/luacrypto/index.html
1490 <http://mkottman.github.io/luacrypto/index.html>`_
1491
1492* `https://github.com/brunoos/luasec/wiki
1493 <https://github.com/brunoos/luasec/wiki>`_
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001494