moonbridge

annotate reference.txt @ 323:1cd58b8efa23

Add -L/usr/lib to ld call for compiling on FreeBSD
author jbe
date Sat Oct 12 01:45:43 2019 +0200 (2019-10-12)
parents 15132b3c053d
children 62901393deb0
rev   line source
jbe@0 1
jbe@0 2 Moonbridge reference
jbe@0 3 ====================
jbe@0 4
jbe@0 5
jbe@0 6
jbe@52 7 Global function listen{...}
jbe@0 8 ---------------------------
jbe@0 9
jbe@0 10 This function initializes the Moonbridge Network Server. It may be called
jbe@0 11 multiple times. However, it is not allowed to register additional listeners by
jbe@234 12 calling listen{...} from a "prepare", "connect", or "finish" handler.
jbe@0 13
jbe@234 14 See file "example.lua" for parametrization of the listen{...} function.
jbe@0 15
jbe@0 16 Warning: Moonbridge will fork the Lua environment to handle parallel requests.
jbe@0 17 Functions provided as "prepare", "connect", and "finish" handlers may access
jbe@0 18 global variables, but for every child process these global variables will not
jbe@0 19 be shared! If you require a global state, a DBMS, cache server, or similar is
jbe@0 20 necessary.
jbe@0 21
jbe@0 22
jbe@0 23
jbe@50 24 Global function timeout(...)
jbe@50 25 ----------------------------
jbe@50 26
jbe@50 27 Calling this function with a positive number (time in seconds) sets a timer
jbe@50 28 that kills the current process after the selected time runs out. The remaining
jbe@50 29 time can be queried by calling this function without arguments.
jbe@50 30
jbe@50 31 Calling this function with a single argument that is the number zero will
jbe@50 32 disable the timeout.
jbe@50 33
jbe@50 34 Another mode of operation is selected by passing two arguments: a time (in
jbe@50 35 seconds) as first argument and a function as second argument. In this case, a
jbe@50 36 sub-timer will be used to limit the execution time of the function. In case of
jbe@50 37 timeout, the process will be killed (and the timeout function does not return).
jbe@50 38 If the time for the sub-timer is longer than a previously set timeout (using
jbe@50 39 the timeout(...) function with one argument), the shorter timeout (of the
jbe@50 40 previous call of timeout(...)) will have precedence.
jbe@50 41
jbe@52 42 Timers are also automatically reset (disabled) when a handler (prepare handler
jbe@52 43 or connect handler) returns. To shutdown processes after a certain time waiting
jbe@52 44 for a new request, use the idle_time parameter of the listen function.
jbe@52 45
jbe@50 46
jbe@50 47
jbe@0 48 Socket object passed to "connect" handler
jbe@0 49 -----------------------------------------
jbe@0 50
jbe@0 51 For every incoming connection, the registered "connect" handler is called with
jbe@0 52 a single socket object as argument, which is described below:
jbe@0 53
jbe@0 54
jbe@94 55 ### socket:close()
jbe@0 56
jbe@0 57 Closes the socket connection (input and output stream) by flushing all data and
jbe@94 58 sending a TCP FIN packet.
jbe@91 59
jbe@91 60 Returns true on success, or nil plus error message in case of an I/O error.
jbe@91 61 Using this method on sockets that have already been closed (or reset) will
jbe@91 62 throw an error.
jbe@0 63
jbe@0 64 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
jbe@94 65 when network connections are used. All pending input data should have been read
jbe@94 66 (or drained) before calling socket:close(). Use socket:finish() to send a
jbe@94 67 TCP FIN packet to the peer before waiting for EOF from the peer.
jbe@91 68
jbe@218 69 A socket passed to the "connect" handler will be closed automatically if it was
jbe@218 70 not closed by the "connect" handler and if the "connect" handler returns
jbe@218 71 normally (i.e. without throwing an error). If the "connect" handler throws an
jbe@218 72 error, then the socket will be reset. See socket:reset().
jbe@218 73
jbe@91 74
jbe@91 75 ### socket:drain(maxlen, terminator)
jbe@0 76
jbe@91 77 Same as socket:read(maxlen, terminator), but discards the input and returns the
jbe@143 78 number of discarded bytes (as first return value) and the status code ("term",
jbe@143 79 "maxlen", "eof" as second return value).
jbe@91 80
jbe@91 81 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 82 second return value) are returned.
jbe@0 83
jbe@0 84
jbe@144 85 ### socket:drain_call(waitfunc, maxlen, terminator)
jbe@144 86
jbe@314 87 Same as socket:drain(maxlen, terminator), but calls waitfunc(socket, "r", first
jbe@314 88 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
jbe@314 89 the reading is blocked.
jbe@144 90
jbe@144 91
jbe@91 92 ### socket:drain_nb(maxlen, terminator)
jbe@0 93
jbe@143 94 Same as socket:drain(maxlen, terminator), but non-blocking. The status code
jbe@143 95 (which is returned as second return value) may therefore be "term", "maxlen",
jbe@143 96 "eof", or "block".
jbe@91 97
jbe@91 98 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 99 second return value) are returned.
jbe@91 100
jbe@0 101
jbe@144 102 ### socket:drain_yield(maxlen, terminator)
jbe@144 103
jbe@144 104 Alias for socket:drain_call(coroutine.yield, maxlen, terminator)
jbe@144 105
jbe@144 106
jbe@94 107 ### socket:finish()
jbe@94 108
jbe@94 109 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
jbe@94 110 still possible. When there is no more input data to be read, the connection
jbe@94 111 should finally be closed with socket:close().
jbe@94 112
jbe@94 113 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
jbe@94 114 the underlying socket and emulates EOF on subsequent reads. Also in this case,
jbe@94 115 the connection should be finally closed with socket:close().
jbe@94 116
jbe@94 117
jbe@91 118 ### socket:flush(...)
jbe@91 119
jbe@91 120 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
jbe@91 121 data is passed to the operating system).
jbe@91 122
jbe@91 123 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 124 second return value) are returned. On success, the socket userdata object is
jbe@91 125 returned.
jbe@91 126
jbe@0 127
jbe@145 128 ### socket:flush_call(waitfunc, ...)
jbe@145 129
jbe@314 130 Same as socket:flush(...), but calls waitfunc(socket, "w", first,
jbe@314 131 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
jbe@314 132 the writing is blocked.
jbe@145 133
jbe@145 134
jbe@91 135 ### socket:flush_nb(...)
jbe@91 136
jbe@91 137 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
jbe@91 138 pending data is passed to the operating system). The total number of bytes that
jbe@91 139 could not be passed yet to the operating system is returned. Zero is returned
jbe@91 140 if all data could be flushed out.
jbe@91 141
jbe@91 142 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 143 second return value) are returned.
jbe@0 144
jbe@0 145
jbe@145 146 ### socket:flush_yield(...)
jbe@145 147
jbe@145 148 Alias for socket:flush_call(coroutine.yield, ...)
jbe@145 149
jbe@145 150
jbe@0 151 ### socket.interval
jbe@0 152
jbe@0 153 Set to the name of an interval timer if the "connect" handler was called due to
jbe@0 154 an elapsed interval timer. Otherwise nil.
jbe@0 155
jbe@0 156
jbe@0 157 ### socket.local_ip4
jbe@0 158
jbe@0 159 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
jbe@0 160 string.
jbe@0 161
jbe@0 162
jbe@0 163 ### socket.local_ip6
jbe@0 164
jbe@0 165 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
jbe@0 166 a string.
jbe@0 167
jbe@0 168
jbe@0 169 ### socket.local_tcpport
jbe@0 170
jbe@0 171 Local TCP port used for the connection.
jbe@0 172
jbe@0 173
jbe@91 174 ### socket:read(maxlen, terminator)
jbe@0 175
jbe@143 176 Reads up to maxlen bytes or until an optional termination character is
jbe@91 177 encountered (which is included in the result). The maxlen value may be nil, in
jbe@91 178 which case there is no limit on the number of bytes read.
jbe@0 179
jbe@91 180 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 181 second return value) are returned.
jbe@0 182
jbe@143 183 In all other cases (including EOF), the following two values are returned:
jbe@143 184
jbe@143 185 - a string containing the bytes read (first return value, may be empty string)
jbe@143 186 - a status code equal to "term", "maxlen", or "eof" (second return value)
jbe@143 187
jbe@143 188 If an EOF is encountered before all data could be read, then "eof" is returned
jbe@143 189 as second return value. If maxlen bytes have been read and no termination
jbe@143 190 character has been read, then "maxlen" is returned as second return value. If
jbe@143 191 the termination character is the last character of the read string, the second
jbe@143 192 return value will be "term".
jbe@143 193
jbe@0 194
jbe@140 195 ### socket:read_call(waitfunc, maxlen, terminator)
jbe@140 196
jbe@314 197 Same as socket:read(maxlen, terminator), but calls waitfunc(socket, "r", first,
jbe@314 198 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
jbe@314 199 the reading is blocked.
jbe@140 200
jbe@140 201
jbe@91 202 ### socket:read_nb(maxlen, terminator)
jbe@91 203
jbe@143 204 Same as socket:read(maxlen, terminator), but does not block.
jbe@91 205
jbe@91 206 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 207 second return value) are returned.
jbe@78 208
jbe@143 209 In all other cases (including EOF), the following two values are returned:
jbe@143 210
jbe@143 211 - a string containing the bytes read (first return value, may be empty string)
jbe@143 212 - a status code equal to "term", "maxlen", "eof", "block" (second return value)
jbe@143 213
jbe@143 214 The status code "block" as second return value is used if the function returned
jbe@143 215 prematurely because it would block otherwise. In this case, the first return
jbe@143 216 value is a string that contains the bytes that could be read without blocking.
jbe@143 217
jbe@78 218
jbe@140 219 ### socket:read_yield(maxlen, terminator)
jbe@140 220
jbe@140 221 Alias for socket:read_call(coroutine.yield, maxlen, terminator)
jbe@140 222
jbe@140 223
jbe@0 224 ### socket.remote_ip4
jbe@0 225
jbe@0 226 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
jbe@0 227 a string.
jbe@0 228
jbe@0 229
jbe@0 230 ### socket.remote_ip6
jbe@0 231
jbe@0 232 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
jbe@0 233 a string.
jbe@0 234
jbe@0 235
jbe@0 236 ### socket.remote_tcpport
jbe@0 237
jbe@0 238 Remote TCP port used for the connection.
jbe@0 239
jbe@0 240
jbe@91 241 ### socket:reset()
jbe@91 242
jbe@218 243 Alias for socket:close(). Closes the socket connection by sending a TCP RST
jbe@218 244 packet if possible to indicate error condition. This is the default operation
jbe@218 245 when a socket handle gets garbage collected or the process is terminated
jbe@218 246 abnormally.
jbe@91 247
jbe@114 248 Returns true on success, or nil (as first return value) plus error message (as
jbe@114 249 second return value) in case of an I/O error. Using this method on sockets that
jbe@91 250 have already been closed (or reset) will throw an error.
jbe@91 251
jbe@91 252 Warning: Previously sent (and flushed) data may be lost during transmission.
jbe@91 253
jbe@91 254
jbe@0 255 ### socket:write(...)
jbe@0 256
jbe@91 257 Takes a variable number of strings and sends them to the peer. The operation is
jbe@91 258 buffered, so to actually send out the data, it is necessary to eventually call
jbe@91 259 socket:flush(), socket:finish(), or socket:close().
jbe@91 260
jbe@91 261 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 262 second return value) are returned. On success, the socket userdata object is
jbe@91 263 returned.
jbe@91 264
jbe@91 265
jbe@145 266 ### socket:write_call(waitfunc, ...)
jbe@145 267
jbe@314 268 Same as socket:write(...), but calls waitfunc(socket, "w", first,
jbe@314 269 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
jbe@314 270 the writing is blocked.
jbe@145 271
jbe@145 272
jbe@91 273 ### socket:write_nb(...)
jbe@91 274
jbe@91 275 Takes a variable number of strings and sends them to the peer. The operation is
jbe@91 276 buffered, so to actually send out the data, it is necessary to eventually call
jbe@91 277 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
jbe@91 278
jbe@91 279 This function always returns immediately (i.e. it does not block). If all data
jbe@91 280 (but a small buffered portion) could be sent out, then zero is returned.
jbe@91 281 Otherwise, all arguments that could not be sent are stored in a buffer of
jbe@91 282 unlimited size (up to memory capabilities) and an integer is returned that
jbe@91 283 indicates the number of bytes currently in the buffer.
jbe@91 284
jbe@91 285 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 286 second return value) are returned.
jbe@0 287
jbe@0 288
jbe@145 289 ### socket:write_yield(...)
jbe@145 290
jbe@145 291 Alias for socket:write_call(coroutine.yield, ...)
jbe@145 292
jbe@145 293
jbe@0 294
jbe@98 295 I/O library
jbe@98 296 -----------
jbe@98 297
jbe@98 298 The Moonbridge Network Server for Lua Applications comes with its own I/O
jbe@98 299 library to support blocking as well as nonblocking I/O operations.
jbe@98 300
jbe@114 301 All methods on an I/O handle (e.g. socket) are described in the previous
jbe@114 302 section regarding the "socket" object. All other functions of the library are
jbe@114 303 listed below.
jbe@114 304
jbe@114 305
jbe@288 306 ### moonbridge_io.catch_sigterm()
jbe@288 307
jbe@288 308 This function installs a signal handler for SIGTERM. Instead of causing
jbe@288 309 immediate process termination, the behavior of moonbridge_io.poll(...) is
jbe@288 310 modified.
jbe@288 311
jbe@288 312 See moonbridge_io.poll(...) for further information.
jbe@288 313
jbe@288 314
jbe@205 315 ### moonbridge_io.exec(command, arg1, arg2, ...)
jbe@205 316
jbe@296 317 Executes the given command and returns a child handle with three sockets named
jbe@205 318 "stdin", "stdout", and "stderr" as well as the following methods:
jbe@205 319
jbe@205 320 - :kill(signal)
jbe@205 321 - :wait()
jbe@205 322 - :wait_nb()
jbe@205 323 - :wait_call(waitfunc)
jbe@205 324 - :wait_yield()
jbe@205 325
jbe@281 326 Use :kill(signal) to terminate the process with the given signal (defaults to 9
jbe@281 327 for SIGKILL).
jbe@205 328
jbe@205 329 The :wait() method will wait for the process to terminate and return its exit
jbe@205 330 code. If the process was terminated by a signal, a negative integer is returned
jbe@205 331 which corresponds to the respective positive signal number.
jbe@205 332
jbe@205 333 The method :wait_nb() is the same as :wait(), except that it does not block but
jbe@219 334 returns false (plus a notice as second return value) if the child process has
jbe@219 335 not terminated yet.
jbe@205 336
jbe@315 337 The method :wait_call() is the same as :wait() but calls waitfunc(child_handle,
jbe@315 338 "r", first, moonbridge_io) (in an infinite loop, first=true only on first call)
jbe@315 339 as long as the process is still running.
jbe@205 340
jbe@205 341 The method :wait_yield() is an alias for :wait_call(coroutine.yield).
jbe@205 342
jbe@296 343 It is possible to wait for process termination by including the child handle
jbe@296 344 in the input_set of the moonbridge_io.poll(...) call.
jbe@296 345
jbe@233 346 moonbridge_io.exec(...) returns nil (as first return value) plus an error
jbe@233 347 message (as second return value) in case of error.
jbe@233 348
jbe@205 349
jbe@286 350 ### moonbridge_io.getpid()
jbe@286 351
jbe@286 352 Returns the current PID.
jbe@286 353
jbe@286 354
jbe@114 355 ### moonbridge_io.localconnect(path)
jbe@114 356
jbe@114 357 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
jbe@114 358 a socket object on success, or nil (as first return value) plus an error
jbe@114 359 message (as second return value) in case of error.
jbe@114 360
jbe@114 361
jbe@114 362 ### moonbridge_io.localconnect_nb(path)
jbe@114 363
jbe@114 364 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
jbe@114 365 a socket object on success, or nil (as first return value) plus an error
jbe@114 366 message (as second return value) in case of error.
jbe@114 367
jbe@114 368 Same as moonbridge_io.localconnect(path), except that this function does not
jbe@114 369 block and immediately returns a socket object.
jbe@114 370
jbe@114 371 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 372 second return value) may be returned. However, connection errors may also be
jbe@114 373 reported on first read or write on the socket.
jbe@114 374
jbe@114 375
jbe@114 376 ### moonbridge_io.locallisten(path)
jbe@114 377
jbe@114 378 Attempts to create a local socket (also known as Unix Domain Socket) to accept
jbe@118 379 incoming connections. If the file does already exist and is a socket, then it
jbe@118 380 is deleted automatically before being re-created.
jbe@114 381
jbe@114 382 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@220 383 second return value) may be returned. On success, a listener object is returned
jbe@114 384 which supports the methods :accept(), :accept_nb(), and :close().
jbe@114 385
jbe@220 386 The method :accept() blocks until a new incoming connection is available, in
jbe@114 387 which case a socket object is returned.
jbe@114 388
jbe@114 389 The method :accept_nb() works like :accept(), except that the call is
jbe@114 390 nonblocking and returns false (plus a notice as second return value) in case no
jbe@114 391 incoming connection is available. It is possible to wait for an incoming
jbe@114 392 connection by including the listener object in the input_set of the
jbe@114 393 moonbridge_io.poll(...) call.
jbe@114 394
jbe@114 395 The method :close() will close the listening socket. In case of local sockets
jbe@114 396 (Unix Domain Sockets), the socket will not be unlinked in the file system.
jbe@114 397
jbe@114 398 I/O errors by the methods of the listener object are also reported by returning
jbe@114 399 nil (as first return value) plus an error message (as second return value).
jbe@114 400
jbe@98 401
jbe@284 402 ### moonbridge_io.poll(input_set, output_set, timeout, wakeup_on_sigterm)
jbe@106 403
jbe@106 404 This function waits for at least one of the given file descriptors and/or
jbe@106 405 I/O handles to be ready for input or output. The two sets of file descriptors
jbe@106 406 and/or handles must contain the file descriptor or handle as a key, and a value
jbe@220 407 which does evaluate to true, e.g. input_set = {[socketA] = true}. If a set is
jbe@220 408 nil, it is treated as being empty.
jbe@106 409
jbe@296 410 The input_set may also contain listeners (to wait for incoming connections) and
jbe@296 411 child handles (to wait for process termination).
jbe@296 412
jbe@288 413 If the 4th parameter (wakeup_on_sigterm) is set to true, then the function
jbe@288 414 returns immediately if the process received at least one SIGTERM signal after
jbe@289 415 moonbridge_io.catch_sigterm() has been called for the first time. Three values
jbe@289 416 are returned if a timeout happened or a SIGTERM has been received: false as
jbe@289 417 first return value, a message string as second return value (that may, for
jbe@289 418 example, be used for assert(...)), and a boolean as third return value which
jbe@289 419 indicates whether the function prematurely returned because of SIGTERM.
jbe@284 420
jbe@288 421 If the 4th parameter (wakeup_on_sigterm) is omitted or set to false, then the
jbe@288 422 function only returns false as first return value if a timeout happened. In
jbe@289 423 this case, the second return value also will be set to an appropriate message
jbe@289 424 string such that assert(moonbridge_io.poll(...)) can be used to throw an error.
jbe@288 425
jbe@289 426 In all other cases, the function returns true as a single return value. The
jbe@289 427 function may also return true (for technical reasons) if signals other than
jbe@289 428 SIGTERM have been received during waiting.
jbe@266 429
jbe@286 430 Note that the function is not thread-safe when the 4th parameter is set to
jbe@286 431 true.
jbe@286 432
jbe@266 433
jbe@98 434 ### moonbridge_io.tcpconnect(hostname, port)
jbe@98 435
jbe@98 436 Tries to open a TCP connection with the given host and TCP port number. Returns
jbe@114 437 a socket object on success, or nil (as first return value) plus an error
jbe@114 438 message (as second return value) in case of error.
jbe@98 439
jbe@98 440
jbe@99 441 ### moonbridge_io.tcpconnect_nb(hostname, port)
jbe@99 442
jbe@99 443 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
jbe@99 444 does not block and immediately returns a socket object.
jbe@99 445
jbe@102 446 Note: The current implementation still blocks during the DNS lookup. Use a
jbe@102 447 numeric IP address as hostname to be truly nonblocking.
jbe@102 448
jbe@99 449 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 450 second return value) may be returned. However, connection errors may also be
jbe@99 451 reported on first read or write on the socket.
jbe@99 452
jbe@99 453
jbe@114 454 ### moonbridge_io.tcplisten(hostname, port)
jbe@114 455
jbe@114 456 Attempts to open a TCP port for listening. To listen on the loopback interface,
jbe@114 457 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
jbe@114 458 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
jbe@114 459 "0.0.0.0" (IPv4) respectively.
jbe@114 460
jbe@114 461 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 462 second return value) may be returned. On success, a listener object is returned
jbe@114 463 which supports the methods :accept(), :accept_nb(), and :close(). See reference
jbe@114 464 for moonbridge.io_locallisten(...).
jbe@114 465
jbe@114 466
jbe@235 467 ### moonbridge_io.timeref(previous)
jbe@235 468
jbe@235 469 Helper function which returns a time reference (in SI-seconds). If a value is
jbe@235 470 passed as an optional argument to the function, then that value is substracted
jbe@235 471 from the result. A common idiom is:
jbe@235 472
jbe@235 473 local starttime = moonbridge_io.timeref()
jbe@235 474 [...]
jbe@235 475 while true do
jbe@235 476 [...]
jbe@235 477 if not moonbridge_io.poll(
jbe@235 478 input_set,
jbe@235 479 output_set,
jbe@235 480 timeout - moonbridge_io.timeref(starttime)
jbe@235 481 ) then
jbe@273 482 error("Timeout")
jbe@235 483 end
jbe@235 484 [...]
jbe@235 485 end
jbe@235 486
jbe@235 487
jbe@98 488
jbe@0 489 HTTP module
jbe@0 490 -----------
jbe@0 491
jbe@220 492 The HTTP module exports the function moonbridge_http.generate_handler(callback)
jbe@224 493 that converts an HTTP handler to a "connect" handler. See file "helloworld.lua"
jbe@224 494 for a simple example or "example_application.lua" for a more complex example of
jbe@224 495 invocation. A table with options may be passed either as a second argument, or
jbe@224 496 as a first argument preceeding the callback function (whichever is more
jbe@224 497 convenient).
jbe@0 498
jbe@0 499 The following options are supported:
jbe@0 500
jbe@0 501 - request_body_size_limit: maximum size of payload of HTTP request body
jbe@0 502 (transfer encoding is allowed to add a limited amount of extra data)
jbe@0 503 - chunk_size: optional default value for maximum_input_chunk_size and
jbe@0 504 minimum_output_chunk_size
jbe@0 505 - request_header_size_limit: maximum size of HTTP request headers
jbe@0 506 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
jbe@0 507 certain POST fields (bigger chunks will be fragmented automatically)
jbe@0 508 - minimum_output_chunk_size: minimum size for a chunk when sending a response
jbe@0 509 body (smaller chunks will be buffered and concatenated with future data;
jbe@0 510 ignored when request:flush() is called)
jbe@0 511 - static_headers: a set of headers to be included in every HTTP response
jbe@0 512 (may be a string, a table or strings, or a table of key-value pairs)
jbe@0 513
jbe@0 514 The callback function receives a single request object as argument, which is
jbe@0 515 described below.
jbe@0 516
jbe@0 517
jbe@0 518 ### request.body
jbe@0 519
jbe@0 520 The request body (without headers) as a string. Accessing this value makes
jbe@0 521 further access to request.post_params and request.post_params_list, or
jbe@0 522 invocation of request:stream_request_body(...) impossible.
jbe@0 523
jbe@0 524
jbe@60 525 ### request:close_after_finish()
jbe@60 526
jbe@60 527 Closes the connection after answering the request.
jbe@60 528
jbe@60 529 This method can only be called before the HTTP response header section has been
jbe@60 530 finished (i.e. before request:finish_headers(), request:send_data(...), or
jbe@60 531 request:finish() were called), but it may be called before a status code has
jbe@60 532 been sent using request:send_status(...).
jbe@60 533
jbe@60 534 A corresponding "Connection: close" header is automatically sent.
jbe@60 535
jbe@184 536 See also request:monologue().
jbe@184 537
jbe@184 538
jbe@184 539 ### request:consume_input()
jbe@184 540
jbe@184 541 Starts processing the request body (if existent) to set the values
jbe@184 542 request.post_params, request.post_params_list, request.post_metadata, and
jbe@184 543 and request.post_metadata_list and/or to call POST field stream handlers that
jbe@184 544 have been previously registered with request:stream_post_param(...) or
jbe@184 545 request:stream_post_params(...), or to call a previously registered request
jbe@184 546 body stream handler that was set with request:set_request_body_streamer().
jbe@184 547
jbe@184 548 This method gets invoked automatically when the POST param tables
jbe@184 549 (request.post_params, etc.) are accessed or if request.body is accessed.
jbe@184 550
jbe@60 551
jbe@0 552 ### request.cookies
jbe@0 553
jbe@0 554 A table with all cookies sent by the client.
jbe@0 555
jbe@0 556
jbe@50 557 ### request.faulty
jbe@50 558
jbe@184 559 Normally set to false. In case of a write error on the client connection or
jbe@184 560 certain other unexpected errors, this value is set to true before a Lua error
jbe@184 561 is raised.
jbe@50 562
jbe@50 563 A faulty request handle must not be used, or another Lua error will be raised.
jbe@50 564
jbe@50 565
jbe@0 566 ### request:finish()
jbe@0 567
jbe@224 568 Finishes and flushes a HTTP response. An HTTP status, all headers, and the
jbe@224 569 response body (if applicable) must have been previously sent. May be called
jbe@224 570 multiple times (performs no operation if called on a finished request handle).
jbe@224 571 Gets automatically invoked when the callback handler returns. After calling
jbe@224 572 this method explicitly, no further data may be written.
jbe@0 573
jbe@0 574
jbe@0 575 ### request:finish_headers()
jbe@0 576
jbe@0 577 Finishes and flushes the HTTP response header section. May be called multiple
jbe@0 578 times, as long as the request is not finished completely. This method is
jbe@0 579 automatically invoked if the application is beginning to send a response body.
jbe@0 580 After calling this method, no further headers may be sent.
jbe@0 581
jbe@0 582
jbe@0 583 ### request:flush()
jbe@0 584
jbe@0 585 Flushes any pending output data. Note: In order to mark the end of a response
jbe@0 586 body, it is required to call request:finish().
jbe@0 587
jbe@0 588
jbe@184 589 ### request.fresh
jbe@184 590
jbe@184 591 Set to false whenever the request object has been used (e.g. data has been read
jbe@184 592 or sent out, or a stream handler was installed); true otherwise.
jbe@184 593
jbe@184 594
jbe@0 595 ### request.get_params
jbe@0 596
jbe@0 597 A table that maps field names to their corresponding GET value. If there are
jbe@0 598 several GET values with the given field name, then the first value is used.
jbe@0 599
jbe@35 600 Note: May be implemented through metamethods, but does support iteration
jbe@35 601 through pairs(...).
jbe@35 602
jbe@0 603
jbe@0 604 ### request.get_params_list
jbe@0 605
jbe@0 606 A table that maps field names to a sequence of their corresponding GET values.
jbe@0 607
jbe@35 608 Note: May be implemented through metamethods, but does support iteration
jbe@35 609 through pairs(...).
jbe@35 610
jbe@0 611
jbe@0 612 ### request.headers
jbe@0 613
jbe@0 614 A table that maps (case-insensitively) a HTTP header field name to a sequence
jbe@224 615 of values. For each occurrence of the respective header line, a string entry is
jbe@224 616 created in that sequence. Non-existent headers are mapped to an empty table.
jbe@0 617
jbe@0 618
jbe@0 619 ### request.headers_csv_string
jbe@0 620
jbe@0 621 A table that maps (case-insensitively) a HTTP header field name to a comma
jbe@0 622 separated string. Multiple occurrences of the header with the given field name
jbe@0 623 are automatically merged into the comma separated string.
jbe@0 624
jbe@0 625
jbe@0 626 ### request.headers_csv_table
jbe@0 627
jbe@0 628 A table that maps (case-insensitively) a HTTP header field name to a sequence
jbe@224 629 of values. One entry is created in that sequence for every comma separated
jbe@224 630 value of each header with the given field name.
jbe@0 631
jbe@0 632
jbe@0 633 ### request.headers_flags
jbe@0 634
jbe@0 635 A table that maps (case-insensitively) a HTTP header field name to another
jbe@0 636 table which (again case-insensitively) maps a string to a boolean, depending on
jbe@0 637 whether this string occurred in the list of comma separated values of one
jbe@0 638 header line with the given field name that was the key in the first table.
jbe@0 639
jbe@0 640
jbe@0 641 ### request.headers_value
jbe@0 642
jbe@0 643 A table that maps (case-insensitively) a HTTP header field name to a value. If
jbe@0 644 multiple header lines with the given field name have been received, false is
jbe@0 645 used as value.
jbe@0 646
jbe@0 647
jbe@0 648 ### request.method
jbe@0 649
jbe@0 650 The HTTP request method, e.g. "HEAD", "GET", or "POST".
jbe@0 651
jbe@0 652
jbe@184 653 ### request:monologue()
jbe@184 654
jbe@184 655 Same as request:close_after_finish() but additionally discards all input data
jbe@184 656 immediately.
jbe@184 657
jbe@184 658
jbe@0 659 ### request.path
jbe@0 660
jbe@10 661 The requested path without a leading slash and without the query part (e.g.
jbe@10 662 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
jbe@10 663 see request.query.
jbe@10 664
jbe@10 665 This value will be nil if (and only if) the request method is "OPTIONS" with a
jbe@10 666 request target equal to "*" (see also asterisk-form of request-target in
jbe@10 667 section 5.3.4 in RFC 7230).
jbe@0 668
jbe@0 669
jbe@0 670 ### request.post_metadata
jbe@0 671
jbe@0 672 Only set for multipart/form-data POST requests. A table that maps field names
jbe@0 673 to their corresponding POST metadata table which contains two entries:
jbe@0 674 "file_name" and "content_type". If there are several POST values with the given
jbe@0 675 field name, then the first value/file is used.
jbe@0 676
jbe@224 677 Note: May be implemented through metamethods, but does support iteration
jbe@224 678 through pairs(...).
jbe@224 679
jbe@0 680
jbe@0 681 ### request.post_metadata_list
jbe@0 682
jbe@0 683 Only set for multipart/form-data POST requests. A table that maps field names
jbe@0 684 to a sequence with their corresponding POST metadata tables. Needed if multiple
jbe@0 685 files are uploaded with the same field name.
jbe@0 686
jbe@224 687 Note: May be implemented through metamethods, but does support iteration
jbe@224 688 through pairs(...).
jbe@224 689
jbe@0 690
jbe@0 691 ### request.post_params
jbe@0 692
jbe@0 693 A table that maps field names to their corresponding POST value. If there are
jbe@0 694 several POST values with the given field name, then the first value is used.
jbe@0 695
jbe@35 696 Note: May be implemented through metamethods, but does support iteration
jbe@35 697 through pairs(...).
jbe@35 698
jbe@0 699
jbe@0 700 ### request.post_params_list
jbe@0 701
jbe@0 702 A table that maps field names to a sequence of their corresponding POST values.
jbe@0 703
jbe@35 704 Note: May be implemented through metamethods, but does support iteration
jbe@35 705 through pairs(...).
jbe@35 706
jbe@0 707
jbe@0 708 ### request.query
jbe@0 709
jbe@12 710 Query part of the request target including the leading question mark, e.g.
jbe@12 711 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
jbe@10 712 automatically parsed and made available through request.get_params and
jbe@10 713 request.get_params_list.
jbe@10 714
jbe@10 715 If there is no query part given in the request target, then this string is
jbe@10 716 the empty string. This value will be nil if (and only if) the request method
jbe@10 717 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
jbe@10 718 request-target in section 5.3.4 in RFC 7230).
jbe@0 719
jbe@0 720
jbe@0 721 ### request:send_data(...)
jbe@0 722
jbe@0 723 Sends data as response body. All arguments are converted via tostring(...) and
jbe@0 724 concatenated. May be called multiple times until the request has been finished
jbe@0 725 by calling request:finish().
jbe@0 726
jbe@0 727 If the request method (see request.method) is "HEAD", then calls to
jbe@0 728 request:send_data(...) are automatically ignored.
jbe@0 729
jbe@0 730
jbe@0 731 ### request:send_header(key, value)
jbe@0 732
jbe@0 733 Sends a HTTP response header that consists of the given key and the given
jbe@0 734 value. Note: Key and value must be provided as separate arguments. Before any
jbe@0 735 headers can be sent, a HTTP status must have been set with
jbe@0 736 request:send_status(status_string).
jbe@0 737
jbe@0 738
jbe@0 739 ### request:send_status(status_string)
jbe@0 740
jbe@0 741 Sends a HTTP response status that is given as a string consisting of a 3-digit
jbe@0 742 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
jbe@0 743 function must be called once before any headers or response body data may be
jbe@0 744 sent.
jbe@0 745
jbe@0 746
jbe@0 747 ### request.socket
jbe@0 748
jbe@0 749 The underlaying socket. Can be used to force a TCP RST, etc.
jbe@0 750
jbe@0 751
jbe@0 752 ### request:stream_post_param(field_name, callback)
jbe@0 753
jbe@0 754 Registers a stream handler for the given POST parameter. The callback function
jbe@0 755 will be called in the following manner:
jbe@0 756
jbe@0 757 - For the initial chunk, the first chunk gets passed as first argument while a
jbe@0 758 table with metadata ("field_name" and "content_type") gets passed as second
jbe@0 759 argument. In case of an immediate EOF (i.e. an empty file), the passed
jbe@0 760 chunk is the empty string. In all other cases the chunk has a length greater
jbe@0 761 than zero.
jbe@0 762 - For any remaining chunks, the respective chunk gets passed as first and only
jbe@0 763 argument (no metadata). Here, the chunk has always a length greater than
jbe@0 764 zero.
jbe@0 765 - To indicate the end of the stream, the callback function is called without
jbe@0 766 arguments. This also happens in case of an immediate EOF (see above).
jbe@0 767
jbe@0 768 In case of an immediate EOF (i.e. an empty file), the callback function is thus
jbe@0 769 called as follows:
jbe@0 770
jbe@0 771 - The first time with an empty string as first argument, and with the metadata
jbe@0 772 as second argument.
jbe@0 773 - The second time without any arguments.
jbe@0 774
jbe@184 775 Note that request:consume_input() needs to be called to enforce streaming to
jbe@184 776 finish.
jbe@184 777
jbe@0 778
jbe@0 779 ### request:stream_post_params(pattern, callback)
jbe@0 780
jbe@0 781 Same as request:stream_post_param(...) but providing a string pattern to match
jbe@0 782 multiple field names (e.g. "^file_[0-9]+$").
jbe@0 783
jbe@0 784
jbe@0 785 ### request:stream_request_body(callback)
jbe@0 786
jbe@184 787 Registeres a stream handler for the whole request body. For each chunk of the
jbe@184 788 request body, the callback function is called with the corresponding chunk. End
jbe@184 789 of data is indicated by passing a nil value to the callback functuion.
jbe@0 790
jbe@184 791 Note that request:consume_input() needs to be called to enforce streaming to
jbe@184 792 finish.
jbe@0 793
jbe@44 794
jbe@184 795 ### request:stream_request_body_now(callback)
jbe@184 796
jbe@184 797 Start streaming of request body immediately. On EOF the function returns and
jbe@184 798 the callback function is *not* called with nil as argument.
jbe@184 799
jbe@184 800

Impressum / About Us