moonbridge

annotate reference.txt @ 52:042bb4854aa6

Improvements to reference (idle_time vs timeout)
author jbe
date Sun Mar 22 11:56:47 2015 +0100 (2015-03-22)
parents 0dd15d642124
children 14ef90c46e16
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@0 55 ### socket:cancel()
jbe@0 56
jbe@0 57 Closes the socket connection by sending a TCP RST package if possible to
jbe@43 58 indicate error condition. Returns true on success, or nil plus error message in
jbe@43 59 case of an I/O error. Using this method on sockets that have already been
jbe@43 60 closed (or canceled) will throw an error.
jbe@0 61
jbe@0 62 Warning: Previously sent (and flushed) data may be lost during transmission.
jbe@0 63
jbe@0 64
jbe@0 65 ### socket:close(timeout)
jbe@0 66
jbe@0 67 Closes the socket connection (input and output stream) by flushing all data and
jbe@43 68 sending a TCP FIN package. Returns true on success, or nil plus error message
jbe@43 69 in case of an I/O error. Using this method on sockets that have already been
jbe@43 70 closed (or canceled) will throw an error.
jbe@0 71
jbe@0 72 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
jbe@0 73 depending on the particular operating system used. All pending input data
jbe@0 74 should have been read before calling socket:close().
jbe@0 75
jbe@0 76 The optional timeout parameter may be used to wait until all data has been sent
jbe@0 77 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
jbe@0 78 happens first. A timeout value of 0 or nil causes immediate return and sending
jbe@0 79 of pending data in background (recommended).
jbe@0 80
jbe@0 81
jbe@0 82 ### socket:flush()
jbe@0 83
jbe@0 84 Alias for socket.output:flush()
jbe@0 85
jbe@0 86
jbe@0 87 ### socket.input
jbe@0 88
jbe@0 89 Lua file handle representing the input stream of the socket connection.
jbe@0 90 Supports the same methods as io.open()'s return values.
jbe@0 91
jbe@0 92
jbe@0 93 ### socket.interval
jbe@0 94
jbe@0 95 Set to the name of an interval timer if the "connect" handler was called due to
jbe@0 96 an elapsed interval timer. Otherwise nil.
jbe@0 97
jbe@0 98
jbe@0 99 ### socket:lines()
jbe@0 100
jbe@0 101 Alias for socket.input:lines()
jbe@0 102
jbe@0 103
jbe@0 104 ### socket.local_ip4
jbe@0 105
jbe@0 106 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
jbe@0 107 string.
jbe@0 108
jbe@0 109
jbe@0 110 ### socket.local_ip6
jbe@0 111
jbe@0 112 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
jbe@0 113 a string.
jbe@0 114
jbe@0 115
jbe@0 116 ### socket.local_tcpport
jbe@0 117
jbe@0 118 Local TCP port used for the connection.
jbe@0 119
jbe@0 120
jbe@0 121 ### socket.output
jbe@0 122
jbe@0 123 Lua file handle representing the output stream of the socket connection.
jbe@0 124 Supports the same methods as io.open()'s return values.
jbe@0 125
jbe@0 126
jbe@0 127 ### socket:read(...)
jbe@0 128
jbe@0 129 Alias for socket.input:read()
jbe@0 130
jbe@0 131
jbe@0 132 ### socket:readuntil(terminator, maxlen)
jbe@0 133
jbe@0 134 Reads as many bytes until a byte equal to the terminator value occurs. An
jbe@0 135 optional maximum length may be specified. The terminating byte is included in
jbe@43 136 the return value (unless the maximum length would be exceeded). On EOF, nil is
jbe@43 137 returned. In case of an I/O error, nil (as first result value) plus an error
jbe@43 138 message (as second result value) is returned.
jbe@0 139
jbe@43 140 This method is also available as :readuntil(...) for any other Lua file handle
jbe@43 141 (including socket.input).
jbe@0 142
jbe@0 143
jbe@0 144 ### socket.remote_ip4
jbe@0 145
jbe@0 146 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
jbe@0 147 a string.
jbe@0 148
jbe@0 149
jbe@0 150 ### socket.remote_ip6
jbe@0 151
jbe@0 152 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
jbe@0 153 a string.
jbe@0 154
jbe@0 155
jbe@0 156 ### socket.remote_tcpport
jbe@0 157
jbe@0 158 Remote TCP port used for the connection.
jbe@0 159
jbe@0 160
jbe@0 161 ### socket:write(...)
jbe@0 162
jbe@0 163 Alias for socket.output:write(...)
jbe@0 164
jbe@0 165
jbe@0 166
jbe@0 167 HTTP module
jbe@0 168 -----------
jbe@0 169
jbe@0 170 The http module exports the function http.generate_handler(callback) that
jbe@0 171 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
jbe@0 172 example of invocation. A table with options may be passed either as a second
jbe@0 173 argument, or as a first argument preceeding the callback function (whichever is
jbe@0 174 more convenient).
jbe@0 175
jbe@0 176 The following options are supported:
jbe@0 177
jbe@0 178 - request_body_size_limit: maximum size of payload of HTTP request body
jbe@0 179 (transfer encoding is allowed to add a limited amount of extra data)
jbe@0 180 - chunk_size: optional default value for maximum_input_chunk_size and
jbe@0 181 minimum_output_chunk_size
jbe@0 182 - request_header_size_limit: maximum size of HTTP request headers
jbe@0 183 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
jbe@0 184 certain POST fields (bigger chunks will be fragmented automatically)
jbe@0 185 - minimum_output_chunk_size: minimum size for a chunk when sending a response
jbe@0 186 body (smaller chunks will be buffered and concatenated with future data;
jbe@0 187 ignored when request:flush() is called)
jbe@0 188 - static_headers: a set of headers to be included in every HTTP response
jbe@0 189 (may be a string, a table or strings, or a table of key-value pairs)
jbe@0 190
jbe@0 191 The callback function receives a single request object as argument, which is
jbe@0 192 described below.
jbe@0 193
jbe@0 194
jbe@0 195 ### request.body
jbe@0 196
jbe@0 197 The request body (without headers) as a string. Accessing this value makes
jbe@0 198 further access to request.post_params and request.post_params_list, or
jbe@0 199 invocation of request:stream_request_body(...) impossible.
jbe@0 200
jbe@0 201
jbe@0 202 ### request.cookies
jbe@0 203
jbe@0 204 A table with all cookies sent by the client.
jbe@0 205
jbe@0 206
jbe@0 207 ### request.defer_reading()
jbe@0 208
jbe@0 209 Disables automatic request body processing on write. Can be called before
jbe@0 210 sending a HTTP status code to send a response before the request has been fully
jbe@0 211 received.
jbe@0 212
jbe@0 213 CAUTION: Responding to a request before the request body has been processed may
jbe@0 214 lead to a deadlock if the browser does not process the response while trying to
jbe@0 215 send the request. Therefore, this function should only be used if:
jbe@0 216
jbe@0 217 - the TCP stack has enough buffer space for the response (i.e. if the response
jbe@0 218 is small enough), and if
jbe@0 219 - a timer is used to cancel the response in case of a deadlock.
jbe@0 220
jbe@0 221 It is recommended to not use this function unless certain performance tweaks
jbe@0 222 are desired.
jbe@0 223
jbe@0 224
jbe@50 225 ### request.faulty
jbe@50 226
jbe@50 227 Normally set to false. In case of a read or write error on the client
jbe@50 228 connection, this value is set to true before a Lua error is raised.
jbe@50 229
jbe@50 230 A faulty request handle must not be used, or another Lua error will be raised.
jbe@50 231
jbe@50 232
jbe@0 233 ### request:finish()
jbe@0 234
jbe@0 235 Finishes and flushes a HTTP response. May be called multiple times. An
jbe@0 236 HTTP status, all headers, and the response body (if applicable) must have been
jbe@0 237 previously sent. After calling this method, no further data may be written.
jbe@0 238
jbe@0 239
jbe@0 240 ### request:finish_headers()
jbe@0 241
jbe@0 242 Finishes and flushes the HTTP response header section. May be called multiple
jbe@0 243 times, as long as the request is not finished completely. This method is
jbe@0 244 automatically invoked if the application is beginning to send a response body.
jbe@0 245 After calling this method, no further headers may be sent.
jbe@0 246
jbe@0 247
jbe@0 248 ### request:flush()
jbe@0 249
jbe@0 250 Flushes any pending output data. Note: In order to mark the end of a response
jbe@0 251 body, it is required to call request:finish().
jbe@0 252
jbe@0 253
jbe@0 254 ### request.get_params
jbe@0 255
jbe@0 256 A table that maps field names to their corresponding GET value. If there are
jbe@0 257 several GET values with the given field name, then the first value is used.
jbe@0 258
jbe@35 259 Note: May be implemented through metamethods, but does support iteration
jbe@35 260 through pairs(...).
jbe@35 261
jbe@0 262
jbe@0 263 ### request.get_params_list
jbe@0 264
jbe@0 265 A table that maps field names to a sequence of their corresponding GET values.
jbe@0 266
jbe@35 267 Note: May be implemented through metamethods, but does support iteration
jbe@35 268 through pairs(...).
jbe@35 269
jbe@0 270
jbe@0 271 ### request.headers
jbe@0 272
jbe@0 273 A table that maps (case-insensitively) a HTTP header field name to a sequence
jbe@0 274 of values. One entry is created for every occurrence of a header line with the
jbe@0 275 given field name).
jbe@0 276
jbe@0 277
jbe@0 278 ### request.headers_csv_string
jbe@0 279
jbe@0 280 A table that maps (case-insensitively) a HTTP header field name to a comma
jbe@0 281 separated string. Multiple occurrences of the header with the given field name
jbe@0 282 are automatically merged into the comma separated string.
jbe@0 283
jbe@0 284
jbe@0 285 ### request.headers_csv_table
jbe@0 286
jbe@0 287 A table that maps (case-insensitively) a HTTP header field name to a sequence
jbe@0 288 of values. One entry is created for every comma separated value of each header
jbe@0 289 with the given field name.
jbe@0 290
jbe@0 291
jbe@0 292 ### request.headers_flags
jbe@0 293
jbe@0 294 A table that maps (case-insensitively) a HTTP header field name to another
jbe@0 295 table which (again case-insensitively) maps a string to a boolean, depending on
jbe@0 296 whether this string occurred in the list of comma separated values of one
jbe@0 297 header line with the given field name that was the key in the first table.
jbe@0 298
jbe@0 299
jbe@0 300 ### request.headers_value
jbe@0 301
jbe@0 302 A table that maps (case-insensitively) a HTTP header field name to a value. If
jbe@0 303 multiple header lines with the given field name have been received, false is
jbe@0 304 used as value.
jbe@0 305
jbe@0 306
jbe@0 307 ### request.method
jbe@0 308
jbe@0 309 The HTTP request method, e.g. "HEAD", "GET", or "POST".
jbe@0 310
jbe@0 311
jbe@0 312 ### request.path
jbe@0 313
jbe@10 314 The requested path without a leading slash and without the query part (e.g.
jbe@10 315 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
jbe@10 316 see request.query.
jbe@10 317
jbe@10 318 This value will be nil if (and only if) the request method is "OPTIONS" with a
jbe@10 319 request target equal to "*" (see also asterisk-form of request-target in
jbe@10 320 section 5.3.4 in RFC 7230).
jbe@0 321
jbe@0 322
jbe@0 323 ### request.post_metadata
jbe@0 324
jbe@0 325 Only set for multipart/form-data POST requests. A table that maps field names
jbe@0 326 to their corresponding POST metadata table which contains two entries:
jbe@0 327 "file_name" and "content_type". If there are several POST values with the given
jbe@0 328 field name, then the first value/file is used.
jbe@0 329
jbe@0 330
jbe@0 331 ### request.post_metadata_list
jbe@0 332
jbe@0 333 Only set for multipart/form-data POST requests. A table that maps field names
jbe@0 334 to a sequence with their corresponding POST metadata tables. Needed if multiple
jbe@0 335 files are uploaded with the same field name.
jbe@0 336
jbe@0 337
jbe@0 338 ### request.post_params
jbe@0 339
jbe@0 340 A table that maps field names to their corresponding POST value. If there are
jbe@0 341 several POST values with the given field name, then the first value is used.
jbe@0 342
jbe@35 343 Note: May be implemented through metamethods, but does support iteration
jbe@35 344 through pairs(...).
jbe@35 345
jbe@0 346
jbe@0 347 ### request.post_params_list
jbe@0 348
jbe@0 349 A table that maps field names to a sequence of their corresponding POST values.
jbe@0 350
jbe@35 351 Note: May be implemented through metamethods, but does support iteration
jbe@35 352 through pairs(...).
jbe@35 353
jbe@0 354
jbe@0 355 ### request.query
jbe@0 356
jbe@12 357 Query part of the request target including the leading question mark, e.g.
jbe@12 358 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
jbe@10 359 automatically parsed and made available through request.get_params and
jbe@10 360 request.get_params_list.
jbe@10 361
jbe@10 362 If there is no query part given in the request target, then this string is
jbe@10 363 the empty string. This value will be nil if (and only if) the request method
jbe@10 364 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
jbe@10 365 request-target in section 5.3.4 in RFC 7230).
jbe@0 366
jbe@0 367
jbe@0 368 ### request:process_request_body()
jbe@0 369
jbe@0 370 Starts processing the request body (if existent) to set the values
jbe@0 371 request.post_params, request.post_params_list, request.post_metadata, and
jbe@0 372 and request.post_metadata_list and/or to call POST field stream handlers that
jbe@0 373 have been previously registered with request:stream_post_param(...) or
jbe@0 374 request:stream_post_params(...).
jbe@0 375
jbe@0 376 This method gets invoked automatically when the POST param tables
jbe@0 377 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
jbe@0 378 deadlocks with the webbrowser). (Note: Automatic request body processing on
jbe@0 379 write may be disabled by calling request:defer_reading().)
jbe@0 380
jbe@0 381 After this method returned, all registered POST field stream handlers have
jbe@0 382 received all data. Registration of other POST field stream handlers is not
jbe@0 383 possible after this method has been called (or after request.post_params_list
jbe@0 384 or request.post_params have been accessed).
jbe@0 385
jbe@0 386
jbe@0 387 ### request:send_data(...)
jbe@0 388
jbe@0 389 Sends data as response body. All arguments are converted via tostring(...) and
jbe@0 390 concatenated. May be called multiple times until the request has been finished
jbe@0 391 by calling request:finish().
jbe@0 392
jbe@0 393 If the request method (see request.method) is "HEAD", then calls to
jbe@0 394 request:send_data(...) are automatically ignored.
jbe@0 395
jbe@0 396
jbe@0 397 ### request:send_header(key, value)
jbe@0 398
jbe@0 399 Sends a HTTP response header that consists of the given key and the given
jbe@0 400 value. Note: Key and value must be provided as separate arguments. Before any
jbe@0 401 headers can be sent, a HTTP status must have been set with
jbe@0 402 request:send_status(status_string).
jbe@0 403
jbe@0 404
jbe@0 405 ### request:send_status(status_string)
jbe@0 406
jbe@0 407 Sends a HTTP response status that is given as a string consisting of a 3-digit
jbe@0 408 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
jbe@0 409 function must be called once before any headers or response body data may be
jbe@0 410 sent.
jbe@0 411
jbe@0 412
jbe@0 413 ### request.socket
jbe@0 414
jbe@0 415 The underlaying socket. Can be used to force a TCP RST, etc.
jbe@0 416
jbe@0 417
jbe@0 418 ### request:stream_post_param(field_name, callback)
jbe@0 419
jbe@0 420 Registers a stream handler for the given POST parameter. The callback function
jbe@0 421 will be called in the following manner:
jbe@0 422
jbe@0 423 - For the initial chunk, the first chunk gets passed as first argument while a
jbe@0 424 table with metadata ("field_name" and "content_type") gets passed as second
jbe@0 425 argument. In case of an immediate EOF (i.e. an empty file), the passed
jbe@0 426 chunk is the empty string. In all other cases the chunk has a length greater
jbe@0 427 than zero.
jbe@0 428 - For any remaining chunks, the respective chunk gets passed as first and only
jbe@0 429 argument (no metadata). Here, the chunk has always a length greater than
jbe@0 430 zero.
jbe@0 431 - To indicate the end of the stream, the callback function is called without
jbe@0 432 arguments. This also happens in case of an immediate EOF (see above).
jbe@0 433
jbe@0 434 In case of an immediate EOF (i.e. an empty file), the callback function is thus
jbe@0 435 called as follows:
jbe@0 436
jbe@0 437 - The first time with an empty string as first argument, and with the metadata
jbe@0 438 as second argument.
jbe@0 439 - The second time without any arguments.
jbe@0 440
jbe@0 441
jbe@0 442 ### request:stream_post_params(pattern, callback)
jbe@0 443
jbe@0 444 Same as request:stream_post_param(...) but providing a string pattern to match
jbe@0 445 multiple field names (e.g. "^file_[0-9]+$").
jbe@0 446
jbe@0 447
jbe@0 448 ### request:stream_request_body(callback)
jbe@0 449
jbe@0 450 Start streaming of request body. For each chunk of the request body, the
jbe@0 451 callback function is called with the corresponding chunk. End of data is
jbe@0 452 indicated through return of request:stream_request_body(...) (not by calling
jbe@0 453 the callback without arguments).
jbe@0 454
jbe@44 455 The function may be called with nil instead of a callback function. In this
jbe@44 456 case, the request body is read and discarded. Only if nil is passed instead of
jbe@44 457 a callback, then the function may also be invoked when the request body has
jbe@44 458 already been read and/or processed. In the latter case, the function performs
jbe@44 459 no operation.
jbe@0 460
jbe@44 461

Impressum / About Us