annotate reference.txt @ 0:f6d3b3f70dab

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

Impressum / About Us