moonbridge

annotate reference.txt @ 44:e835cda61478

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

Impressum / About Us