moonbridge

annotate reference.txt @ 123:20e0d4f51381

Updated chat example
author bsw
date Sat Apr 11 00:20:33 2015 +0200 (2015-04-11)
parents 118e320a7812
children 9ca22af4d4b1
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@0 12 calling listen(...) from a "prepare", "connect", or "finish" handler.
jbe@0 13
jbe@0 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@91 69
jbe@91 70 ### socket:drain(maxlen, terminator)
jbe@0 71
jbe@91 72 Same as socket:read(maxlen, terminator), but discards the input and returns the
jbe@91 73 number of discarded bytes. If no bytes could be read but EOF was encountered,
jbe@91 74 then true is returned.
jbe@91 75
jbe@91 76 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 77 second return value) are returned.
jbe@0 78
jbe@0 79
jbe@91 80 ### socket:drain_nb(maxlen, terminator)
jbe@0 81
jbe@91 82 Same as socket:read_nb(maxlen, terminator), but discards the input and returns
jbe@91 83 the number of discarded bytes. If no bytes could be read but EOF was
jbe@91 84 encountered, then true is returned.
jbe@91 85
jbe@91 86 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 87 second return value) are returned.
jbe@91 88
jbe@0 89
jbe@94 90 ### socket:finish()
jbe@94 91
jbe@94 92 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
jbe@94 93 still possible. When there is no more input data to be read, the connection
jbe@94 94 should finally be closed with socket:close().
jbe@94 95
jbe@94 96 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
jbe@94 97 the underlying socket and emulates EOF on subsequent reads. Also in this case,
jbe@94 98 the connection should be finally closed with socket:close().
jbe@94 99
jbe@94 100
jbe@91 101 ### socket:flush(...)
jbe@91 102
jbe@91 103 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
jbe@91 104 data is passed to the operating system).
jbe@91 105
jbe@91 106 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 107 second return value) are returned. On success, the socket userdata object is
jbe@91 108 returned.
jbe@91 109
jbe@0 110
jbe@91 111 ### socket:flush_nb(...)
jbe@91 112
jbe@91 113 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
jbe@91 114 pending data is passed to the operating system). The total number of bytes that
jbe@91 115 could not be passed yet to the operating system is returned. Zero is returned
jbe@91 116 if all data could be flushed out.
jbe@91 117
jbe@91 118 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 119 second return value) are returned.
jbe@0 120
jbe@0 121
jbe@0 122 ### socket.interval
jbe@0 123
jbe@0 124 Set to the name of an interval timer if the "connect" handler was called due to
jbe@0 125 an elapsed interval timer. Otherwise nil.
jbe@0 126
jbe@0 127
jbe@0 128 ### socket.local_ip4
jbe@0 129
jbe@0 130 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
jbe@0 131 string.
jbe@0 132
jbe@0 133
jbe@0 134 ### socket.local_ip6
jbe@0 135
jbe@0 136 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
jbe@0 137 a string.
jbe@0 138
jbe@0 139
jbe@0 140 ### socket.local_tcpport
jbe@0 141
jbe@0 142 Local TCP port used for the connection.
jbe@0 143
jbe@0 144
jbe@91 145 ### socket:read(maxlen, terminator)
jbe@0 146
jbe@91 147 Read up to maxlen bytes or until an optional termination character is
jbe@91 148 encountered (which is included in the result). The maxlen value may be nil, in
jbe@91 149 which case there is no limit on the number of bytes read.
jbe@0 150
jbe@91 151 If EOF is encountered before any data could be read, then false (as first
jbe@91 152 return value) plus a notice string (as second return value) are returned.
jbe@0 153
jbe@91 154 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 155 second return value) are returned.
jbe@0 156
jbe@0 157
jbe@91 158 ### socket:read_nb(maxlen, terminator)
jbe@91 159
jbe@91 160 Read up to maxlen bytes, until an optional termination character is encountered
jbe@91 161 (which is included in the result), or until no more data is available for
jbe@91 162 reading. The maxlen value may be nil, in which case there is no limit on the
jbe@91 163 number of bytes read.
jbe@78 164
jbe@91 165 If EOF is encountered before any data could be read, then false (as first
jbe@91 166 return value) plus a notice string (as second return value) are returned.
jbe@78 167
jbe@91 168 If no data was available for reading, but no EOF was encountered, then an empty
jbe@91 169 string is returned.
jbe@91 170
jbe@91 171 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 172 second return value) are returned.
jbe@78 173
jbe@78 174
jbe@0 175 ### socket.remote_ip4
jbe@0 176
jbe@0 177 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
jbe@0 178 a string.
jbe@0 179
jbe@0 180
jbe@0 181 ### socket.remote_ip6
jbe@0 182
jbe@0 183 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
jbe@0 184 a string.
jbe@0 185
jbe@0 186
jbe@0 187 ### socket.remote_tcpport
jbe@0 188
jbe@0 189 Remote TCP port used for the connection.
jbe@0 190
jbe@0 191
jbe@91 192 ### socket:reset()
jbe@91 193
jbe@91 194 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
jbe@91 195 packet if possible to indicate error condition.
jbe@91 196
jbe@114 197 Returns true on success, or nil (as first return value) plus error message (as
jbe@114 198 second return value) in case of an I/O error. Using this method on sockets that
jbe@91 199 have already been closed (or reset) will throw an error.
jbe@91 200
jbe@91 201 Warning: Previously sent (and flushed) data may be lost during transmission.
jbe@91 202
jbe@91 203
jbe@0 204 ### socket:write(...)
jbe@0 205
jbe@91 206 Takes a variable number of strings and sends them to the peer. The operation is
jbe@91 207 buffered, so to actually send out the data, it is necessary to eventually call
jbe@91 208 socket:flush(), socket:finish(), or socket:close().
jbe@91 209
jbe@91 210 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 211 second return value) are returned. On success, the socket userdata object is
jbe@91 212 returned.
jbe@91 213
jbe@91 214
jbe@91 215 ### socket:write_nb(...)
jbe@91 216
jbe@91 217 Takes a variable number of strings and sends them to the peer. The operation is
jbe@91 218 buffered, so to actually send out the data, it is necessary to eventually call
jbe@91 219 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
jbe@91 220
jbe@91 221 This function always returns immediately (i.e. it does not block). If all data
jbe@91 222 (but a small buffered portion) could be sent out, then zero is returned.
jbe@91 223 Otherwise, all arguments that could not be sent are stored in a buffer of
jbe@91 224 unlimited size (up to memory capabilities) and an integer is returned that
jbe@91 225 indicates the number of bytes currently in the buffer.
jbe@91 226
jbe@91 227 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 228 second return value) are returned.
jbe@0 229
jbe@0 230
jbe@0 231
jbe@98 232 I/O library
jbe@98 233 -----------
jbe@98 234
jbe@98 235 The Moonbridge Network Server for Lua Applications comes with its own I/O
jbe@98 236 library to support blocking as well as nonblocking I/O operations.
jbe@98 237
jbe@114 238 All methods on an I/O handle (e.g. socket) are described in the previous
jbe@114 239 section regarding the "socket" object. All other functions of the library are
jbe@114 240 listed below.
jbe@114 241
jbe@114 242
jbe@114 243 ### moonbridge_io.localconnect(path)
jbe@114 244
jbe@114 245 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
jbe@114 246 a socket object on success, or nil (as first return value) plus an error
jbe@114 247 message (as second return value) in case of error.
jbe@114 248
jbe@114 249
jbe@114 250 ### moonbridge_io.localconnect_nb(path)
jbe@114 251
jbe@114 252 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
jbe@114 253 a socket object on success, or nil (as first return value) plus an error
jbe@114 254 message (as second return value) in case of error.
jbe@114 255
jbe@114 256 Same as moonbridge_io.localconnect(path), except that this function does not
jbe@114 257 block and immediately returns a socket object.
jbe@114 258
jbe@114 259 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 260 second return value) may be returned. However, connection errors may also be
jbe@114 261 reported on first read or write on the socket.
jbe@114 262
jbe@114 263
jbe@114 264 ### moonbridge_io.locallisten(path)
jbe@114 265
jbe@114 266 Attempts to create a local socket (also known as Unix Domain Socket) to accept
jbe@118 267 incoming connections. If the file does already exist and is a socket, then it
jbe@118 268 is deleted automatically before being re-created.
jbe@114 269
jbe@114 270 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 271 second return value) may be returned.On success, a listener object is returned
jbe@114 272 which supports the methods :accept(), :accept_nb(), and :close().
jbe@114 273
jbe@114 274 The method :accept() blocks until a new incoming connection is available in
jbe@114 275 which case a socket object is returned.
jbe@114 276
jbe@114 277 The method :accept_nb() works like :accept(), except that the call is
jbe@114 278 nonblocking and returns false (plus a notice as second return value) in case no
jbe@114 279 incoming connection is available. It is possible to wait for an incoming
jbe@114 280 connection by including the listener object in the input_set of the
jbe@114 281 moonbridge_io.poll(...) call.
jbe@114 282
jbe@114 283 The method :close() will close the listening socket. In case of local sockets
jbe@114 284 (Unix Domain Sockets), the socket will not be unlinked in the file system.
jbe@114 285
jbe@114 286 I/O errors by the methods of the listener object are also reported by returning
jbe@114 287 nil (as first return value) plus an error message (as second return value).
jbe@114 288
jbe@98 289
jbe@106 290 ### moonbridge_io.poll(input_set, output_set, timeout)
jbe@106 291
jbe@106 292 This function waits for at least one of the given file descriptors and/or
jbe@106 293 I/O handles to be ready for input or output. The two sets of file descriptors
jbe@106 294 and/or handles must contain the file descriptor or handle as a key, and a value
jbe@106 295 which does evaluate to true. If a set is nil, it is treated as being empty.
jbe@106 296
jbe@106 297 Returns true when at least one file descriptor or handle is ready for reading
jbe@106 298 or writing respectively. Returns false (as first return value) plus a status
jbe@106 299 message (as second return value) in case of timeout or when a signal was
jbe@106 300 received.
jbe@106 301
jbe@106 302
jbe@98 303 ### moonbridge_io.tcpconnect(hostname, port)
jbe@98 304
jbe@98 305 Tries to open a TCP connection with the given host and TCP port number. Returns
jbe@114 306 a socket object on success, or nil (as first return value) plus an error
jbe@114 307 message (as second return value) in case of error.
jbe@98 308
jbe@98 309
jbe@99 310 ### moonbridge_io.tcpconnect_nb(hostname, port)
jbe@99 311
jbe@99 312 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
jbe@99 313 does not block and immediately returns a socket object.
jbe@99 314
jbe@102 315 Note: The current implementation still blocks during the DNS lookup. Use a
jbe@102 316 numeric IP address as hostname to be truly nonblocking.
jbe@102 317
jbe@99 318 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 319 second return value) may be returned. However, connection errors may also be
jbe@99 320 reported on first read or write on the socket.
jbe@99 321
jbe@99 322
jbe@114 323 ### moonbridge_io.tcplisten(hostname, port)
jbe@114 324
jbe@114 325 Attempts to open a TCP port for listening. To listen on the loopback interface,
jbe@114 326 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
jbe@114 327 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
jbe@114 328 "0.0.0.0" (IPv4) respectively.
jbe@114 329
jbe@114 330 In case of an I/O error, nil (as first return value) plus an error message (as
jbe@114 331 second return value) may be returned. On success, a listener object is returned
jbe@114 332 which supports the methods :accept(), :accept_nb(), and :close(). See reference
jbe@114 333 for moonbridge.io_locallisten(...).
jbe@114 334
jbe@114 335
jbe@98 336
jbe@0 337 HTTP module
jbe@0 338 -----------
jbe@0 339
jbe@0 340 The http module exports the function http.generate_handler(callback) that
jbe@0 341 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
jbe@0 342 example of invocation. A table with options may be passed either as a second
jbe@0 343 argument, or as a first argument preceeding the callback function (whichever is
jbe@0 344 more convenient).
jbe@0 345
jbe@0 346 The following options are supported:
jbe@0 347
jbe@0 348 - request_body_size_limit: maximum size of payload of HTTP request body
jbe@0 349 (transfer encoding is allowed to add a limited amount of extra data)
jbe@0 350 - chunk_size: optional default value for maximum_input_chunk_size and
jbe@0 351 minimum_output_chunk_size
jbe@0 352 - request_header_size_limit: maximum size of HTTP request headers
jbe@0 353 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
jbe@0 354 certain POST fields (bigger chunks will be fragmented automatically)
jbe@0 355 - minimum_output_chunk_size: minimum size for a chunk when sending a response
jbe@0 356 body (smaller chunks will be buffered and concatenated with future data;
jbe@0 357 ignored when request:flush() is called)
jbe@0 358 - static_headers: a set of headers to be included in every HTTP response
jbe@0 359 (may be a string, a table or strings, or a table of key-value pairs)
jbe@0 360
jbe@0 361 The callback function receives a single request object as argument, which is
jbe@0 362 described below.
jbe@0 363
jbe@0 364
jbe@0 365 ### request.body
jbe@0 366
jbe@0 367 The request body (without headers) as a string. Accessing this value makes
jbe@0 368 further access to request.post_params and request.post_params_list, or
jbe@0 369 invocation of request:stream_request_body(...) impossible.
jbe@0 370
jbe@0 371
jbe@60 372 ### request:close_after_finish()
jbe@60 373
jbe@60 374 Closes the connection after answering the request.
jbe@60 375
jbe@60 376 This method can only be called before the HTTP response header section has been
jbe@60 377 finished (i.e. before request:finish_headers(), request:send_data(...), or
jbe@60 378 request:finish() were called), but it may be called before a status code has
jbe@60 379 been sent using request:send_status(...).
jbe@60 380
jbe@60 381 A corresponding "Connection: close" header is automatically sent.
jbe@60 382
jbe@60 383
jbe@0 384 ### request.cookies
jbe@0 385
jbe@0 386 A table with all cookies sent by the client.
jbe@0 387
jbe@0 388
jbe@0 389 ### request.defer_reading()
jbe@0 390
jbe@0 391 Disables automatic request body processing on write. Can be called before
jbe@0 392 sending a HTTP status code to send a response before the request has been fully
jbe@0 393 received.
jbe@0 394
jbe@0 395 CAUTION: Responding to a request before the request body has been processed may
jbe@0 396 lead to a deadlock if the browser does not process the response while trying to
jbe@0 397 send the request. Therefore, this function should only be used if:
jbe@0 398
jbe@0 399 - the TCP stack has enough buffer space for the response (i.e. if the response
jbe@0 400 is small enough), and if
jbe@0 401 - a timer is used to cancel the response in case of a deadlock.
jbe@0 402
jbe@0 403 It is recommended to not use this function unless certain performance tweaks
jbe@0 404 are desired.
jbe@0 405
jbe@0 406
jbe@50 407 ### request.faulty
jbe@50 408
jbe@50 409 Normally set to false. In case of a read or write error on the client
jbe@50 410 connection, this value is set to true before a Lua error is raised.
jbe@50 411
jbe@50 412 A faulty request handle must not be used, or another Lua error will be raised.
jbe@50 413
jbe@50 414
jbe@0 415 ### request:finish()
jbe@0 416
jbe@0 417 Finishes and flushes a HTTP response. May be called multiple times. An
jbe@0 418 HTTP status, all headers, and the response body (if applicable) must have been
jbe@0 419 previously sent. After calling this method, no further data may be written.
jbe@0 420
jbe@0 421
jbe@0 422 ### request:finish_headers()
jbe@0 423
jbe@0 424 Finishes and flushes the HTTP response header section. May be called multiple
jbe@0 425 times, as long as the request is not finished completely. This method is
jbe@0 426 automatically invoked if the application is beginning to send a response body.
jbe@0 427 After calling this method, no further headers may be sent.
jbe@0 428
jbe@0 429
jbe@0 430 ### request:flush()
jbe@0 431
jbe@0 432 Flushes any pending output data. Note: In order to mark the end of a response
jbe@0 433 body, it is required to call request:finish().
jbe@0 434
jbe@0 435
jbe@0 436 ### request.get_params
jbe@0 437
jbe@0 438 A table that maps field names to their corresponding GET value. If there are
jbe@0 439 several GET values with the given field name, then the first value is used.
jbe@0 440
jbe@35 441 Note: May be implemented through metamethods, but does support iteration
jbe@35 442 through pairs(...).
jbe@35 443
jbe@0 444
jbe@0 445 ### request.get_params_list
jbe@0 446
jbe@0 447 A table that maps field names to a sequence of their corresponding GET values.
jbe@0 448
jbe@35 449 Note: May be implemented through metamethods, but does support iteration
jbe@35 450 through pairs(...).
jbe@35 451
jbe@0 452
jbe@0 453 ### request.headers
jbe@0 454
jbe@0 455 A table that maps (case-insensitively) a HTTP header field name to a sequence
jbe@0 456 of values. One entry is created for every occurrence of a header line with the
jbe@0 457 given field name).
jbe@0 458
jbe@0 459
jbe@0 460 ### request.headers_csv_string
jbe@0 461
jbe@0 462 A table that maps (case-insensitively) a HTTP header field name to a comma
jbe@0 463 separated string. Multiple occurrences of the header with the given field name
jbe@0 464 are automatically merged into the comma separated string.
jbe@0 465
jbe@0 466
jbe@0 467 ### request.headers_csv_table
jbe@0 468
jbe@0 469 A table that maps (case-insensitively) a HTTP header field name to a sequence
jbe@0 470 of values. One entry is created for every comma separated value of each header
jbe@0 471 with the given field name.
jbe@0 472
jbe@0 473
jbe@0 474 ### request.headers_flags
jbe@0 475
jbe@0 476 A table that maps (case-insensitively) a HTTP header field name to another
jbe@0 477 table which (again case-insensitively) maps a string to a boolean, depending on
jbe@0 478 whether this string occurred in the list of comma separated values of one
jbe@0 479 header line with the given field name that was the key in the first table.
jbe@0 480
jbe@0 481
jbe@0 482 ### request.headers_value
jbe@0 483
jbe@0 484 A table that maps (case-insensitively) a HTTP header field name to a value. If
jbe@0 485 multiple header lines with the given field name have been received, false is
jbe@0 486 used as value.
jbe@0 487
jbe@0 488
jbe@0 489 ### request.method
jbe@0 490
jbe@0 491 The HTTP request method, e.g. "HEAD", "GET", or "POST".
jbe@0 492
jbe@0 493
jbe@0 494 ### request.path
jbe@0 495
jbe@10 496 The requested path without a leading slash and without the query part (e.g.
jbe@10 497 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
jbe@10 498 see request.query.
jbe@10 499
jbe@10 500 This value will be nil if (and only if) the request method is "OPTIONS" with a
jbe@10 501 request target equal to "*" (see also asterisk-form of request-target in
jbe@10 502 section 5.3.4 in RFC 7230).
jbe@0 503
jbe@0 504
jbe@0 505 ### request.post_metadata
jbe@0 506
jbe@0 507 Only set for multipart/form-data POST requests. A table that maps field names
jbe@0 508 to their corresponding POST metadata table which contains two entries:
jbe@0 509 "file_name" and "content_type". If there are several POST values with the given
jbe@0 510 field name, then the first value/file is used.
jbe@0 511
jbe@0 512
jbe@0 513 ### request.post_metadata_list
jbe@0 514
jbe@0 515 Only set for multipart/form-data POST requests. A table that maps field names
jbe@0 516 to a sequence with their corresponding POST metadata tables. Needed if multiple
jbe@0 517 files are uploaded with the same field name.
jbe@0 518
jbe@0 519
jbe@0 520 ### request.post_params
jbe@0 521
jbe@0 522 A table that maps field names to their corresponding POST value. If there are
jbe@0 523 several POST values with the given field name, then the first value is used.
jbe@0 524
jbe@35 525 Note: May be implemented through metamethods, but does support iteration
jbe@35 526 through pairs(...).
jbe@35 527
jbe@0 528
jbe@0 529 ### request.post_params_list
jbe@0 530
jbe@0 531 A table that maps field names to a sequence of their corresponding POST values.
jbe@0 532
jbe@35 533 Note: May be implemented through metamethods, but does support iteration
jbe@35 534 through pairs(...).
jbe@35 535
jbe@0 536
jbe@0 537 ### request.query
jbe@0 538
jbe@12 539 Query part of the request target including the leading question mark, e.g.
jbe@12 540 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
jbe@10 541 automatically parsed and made available through request.get_params and
jbe@10 542 request.get_params_list.
jbe@10 543
jbe@10 544 If there is no query part given in the request target, then this string is
jbe@10 545 the empty string. This value will be nil if (and only if) the request method
jbe@10 546 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
jbe@10 547 request-target in section 5.3.4 in RFC 7230).
jbe@0 548
jbe@0 549
jbe@0 550 ### request:process_request_body()
jbe@0 551
jbe@0 552 Starts processing the request body (if existent) to set the values
jbe@0 553 request.post_params, request.post_params_list, request.post_metadata, and
jbe@0 554 and request.post_metadata_list and/or to call POST field stream handlers that
jbe@0 555 have been previously registered with request:stream_post_param(...) or
jbe@0 556 request:stream_post_params(...).
jbe@0 557
jbe@0 558 This method gets invoked automatically when the POST param tables
jbe@0 559 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
jbe@0 560 deadlocks with the webbrowser). (Note: Automatic request body processing on
jbe@0 561 write may be disabled by calling request:defer_reading().)
jbe@0 562
jbe@0 563 After this method returned, all registered POST field stream handlers have
jbe@0 564 received all data. Registration of other POST field stream handlers is not
jbe@0 565 possible after this method has been called (or after request.post_params_list
jbe@0 566 or request.post_params have been accessed).
jbe@0 567
jbe@0 568
jbe@0 569 ### request:send_data(...)
jbe@0 570
jbe@0 571 Sends data as response body. All arguments are converted via tostring(...) and
jbe@0 572 concatenated. May be called multiple times until the request has been finished
jbe@0 573 by calling request:finish().
jbe@0 574
jbe@0 575 If the request method (see request.method) is "HEAD", then calls to
jbe@0 576 request:send_data(...) are automatically ignored.
jbe@0 577
jbe@0 578
jbe@0 579 ### request:send_header(key, value)
jbe@0 580
jbe@0 581 Sends a HTTP response header that consists of the given key and the given
jbe@0 582 value. Note: Key and value must be provided as separate arguments. Before any
jbe@0 583 headers can be sent, a HTTP status must have been set with
jbe@0 584 request:send_status(status_string).
jbe@0 585
jbe@0 586
jbe@0 587 ### request:send_status(status_string)
jbe@0 588
jbe@0 589 Sends a HTTP response status that is given as a string consisting of a 3-digit
jbe@0 590 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
jbe@0 591 function must be called once before any headers or response body data may be
jbe@0 592 sent.
jbe@0 593
jbe@0 594
jbe@0 595 ### request.socket
jbe@0 596
jbe@0 597 The underlaying socket. Can be used to force a TCP RST, etc.
jbe@0 598
jbe@0 599
jbe@0 600 ### request:stream_post_param(field_name, callback)
jbe@0 601
jbe@0 602 Registers a stream handler for the given POST parameter. The callback function
jbe@0 603 will be called in the following manner:
jbe@0 604
jbe@0 605 - For the initial chunk, the first chunk gets passed as first argument while a
jbe@0 606 table with metadata ("field_name" and "content_type") gets passed as second
jbe@0 607 argument. In case of an immediate EOF (i.e. an empty file), the passed
jbe@0 608 chunk is the empty string. In all other cases the chunk has a length greater
jbe@0 609 than zero.
jbe@0 610 - For any remaining chunks, the respective chunk gets passed as first and only
jbe@0 611 argument (no metadata). Here, the chunk has always a length greater than
jbe@0 612 zero.
jbe@0 613 - To indicate the end of the stream, the callback function is called without
jbe@0 614 arguments. This also happens in case of an immediate EOF (see above).
jbe@0 615
jbe@0 616 In case of an immediate EOF (i.e. an empty file), the callback function is thus
jbe@0 617 called as follows:
jbe@0 618
jbe@0 619 - The first time with an empty string as first argument, and with the metadata
jbe@0 620 as second argument.
jbe@0 621 - The second time without any arguments.
jbe@0 622
jbe@0 623
jbe@0 624 ### request:stream_post_params(pattern, callback)
jbe@0 625
jbe@0 626 Same as request:stream_post_param(...) but providing a string pattern to match
jbe@0 627 multiple field names (e.g. "^file_[0-9]+$").
jbe@0 628
jbe@0 629
jbe@0 630 ### request:stream_request_body(callback)
jbe@0 631
jbe@0 632 Start streaming of request body. For each chunk of the request body, the
jbe@0 633 callback function is called with the corresponding chunk. End of data is
jbe@0 634 indicated through return of request:stream_request_body(...) (not by calling
jbe@0 635 the callback without arguments).
jbe@0 636
jbe@44 637 The function may be called with nil instead of a callback function. In this
jbe@44 638 case, the request body is read and discarded. Only if nil is passed instead of
jbe@44 639 a callback, then the function may also be invoked when the request body has
jbe@44 640 already been read and/or processed. In the latter case, the function performs
jbe@44 641 no operation.
jbe@0 642
jbe@44 643

Impressum / About Us