1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/reference.txt	Sun Jan 04 19:30:28 2015 +0100
     1.3 @@ -0,0 +1,401 @@
     1.4 +
     1.5 +Moonbridge reference
     1.6 +====================
     1.7 +
     1.8 +
     1.9 +
    1.10 +Global function listen(...)
    1.11 +---------------------------
    1.12 +
    1.13 +This function initializes the Moonbridge Network Server. It may be called
    1.14 +multiple times. However, it is not allowed to register additional listeners by
    1.15 +calling listen(...) from a "prepare", "connect", or "finish" handler.
    1.16 +
    1.17 +See file "example.lua" for parametrization of the listen(...) function.
    1.18 +
    1.19 +Warning: Moonbridge will fork the Lua environment to handle parallel requests.
    1.20 +Functions provided as "prepare", "connect", and "finish" handlers may access
    1.21 +global variables, but for every child process these global variables will not
    1.22 +be shared! If you require a global state, a DBMS, cache server, or similar is
    1.23 +necessary.
    1.24 +
    1.25 +
    1.26 +
    1.27 +Socket object passed to "connect" handler
    1.28 +-----------------------------------------
    1.29 +
    1.30 +For every incoming connection, the registered "connect" handler is called with
    1.31 +a single socket object as argument, which is described below:
    1.32 +
    1.33 +
    1.34 +### socket:cancel()
    1.35 +
    1.36 +Closes the socket connection by sending a TCP RST package if possible to
    1.37 +indicate error condition.
    1.38 +
    1.39 +Warning: Previously sent (and flushed) data may be lost during transmission.
    1.40 +
    1.41 +
    1.42 +### socket:close(timeout)
    1.43 +
    1.44 +Closes the socket connection (input and output stream) by flushing all data and
    1.45 +sending a TCP FIN package. Performs no operation if stream has already been
    1.46 +closed.
    1.47 +
    1.48 +Warning: Pending data on the input stream may cause connection aborts (TCP RST)
    1.49 +depending on the particular operating system used. All pending input data
    1.50 +should have been read before calling socket:close().
    1.51 +
    1.52 +The optional timeout parameter may be used to wait until all data has been sent
    1.53 +out, or until the timeout elapses (in which case a TCP RST is sent) whichever
    1.54 +happens first. A timeout value of 0 or nil causes immediate return and sending
    1.55 +of pending data in background (recommended).
    1.56 +
    1.57 +
    1.58 +### socket:flush()
    1.59 +
    1.60 +Alias for socket.output:flush()
    1.61 +
    1.62 +
    1.63 +### socket.input
    1.64 +
    1.65 +Lua file handle representing the input stream of the socket connection.
    1.66 +Supports the same methods as io.open()'s return values.
    1.67 +
    1.68 +
    1.69 +### socket.interval
    1.70 +
    1.71 +Set to the name of an interval timer if the "connect" handler was called due to
    1.72 +an elapsed interval timer. Otherwise nil.
    1.73 +
    1.74 +
    1.75 +### socket:lines()
    1.76 +
    1.77 +Alias for socket.input:lines()
    1.78 +
    1.79 +
    1.80 +### socket.local_ip4
    1.81 +
    1.82 +Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
    1.83 +string.
    1.84 +
    1.85 +
    1.86 +### socket.local_ip6
    1.87 +
    1.88 +Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
    1.89 +a string.
    1.90 +
    1.91 +
    1.92 +### socket.local_tcpport
    1.93 +
    1.94 +Local TCP port used for the connection.
    1.95 +
    1.96 +
    1.97 +### socket.output
    1.98 +
    1.99 +Lua file handle representing the output stream of the socket connection.
   1.100 +Supports the same methods as io.open()'s return values.
   1.101 +
   1.102 +
   1.103 +### socket:read(...)
   1.104 +
   1.105 +Alias for socket.input:read()
   1.106 +
   1.107 +
   1.108 +### socket:readuntil(terminator, maxlen)
   1.109 +
   1.110 +Reads as many bytes until a byte equal to the terminator value occurs. An
   1.111 +optional maximum length may be specified. The terminating byte is included in
   1.112 +the return value (unless the maximum length would be exceeded).
   1.113 +
   1.114 +Also available as :readuntil(...) method for any other Lua file handle
   1.115 +(including socket.input)
   1.116 +
   1.117 +
   1.118 +### socket.remote_ip4
   1.119 +
   1.120 +Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
   1.121 +a string.
   1.122 +
   1.123 +
   1.124 +### socket.remote_ip6
   1.125 +
   1.126 +Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
   1.127 +a string.
   1.128 +
   1.129 +
   1.130 +### socket.remote_tcpport
   1.131 +
   1.132 +Remote TCP port used for the connection.
   1.133 +
   1.134 +
   1.135 +### socket:write(...)
   1.136 +
   1.137 +Alias for socket.output:write(...)
   1.138 +
   1.139 +
   1.140 +
   1.141 +HTTP module
   1.142 +-----------
   1.143 +
   1.144 +The http module exports the function http.generate_handler(callback) that
   1.145 +converts an HTTP handler to a "connect" handler. See file "example.lua" for an
   1.146 +example of invocation. A table with options may be passed either as a second
   1.147 +argument, or as a first argument preceeding the callback function (whichever is
   1.148 +more convenient).
   1.149 +
   1.150 +The following options are supported:
   1.151 +
   1.152 +- request_body_size_limit: maximum size of payload of HTTP request body
   1.153 +  (transfer encoding is allowed to add a limited amount of extra data)
   1.154 +- chunk_size: optional default value for maximum_input_chunk_size and
   1.155 +  minimum_output_chunk_size
   1.156 +- request_header_size_limit: maximum size of HTTP request headers
   1.157 +- maximum_input_chunk_size: maximum chunk size when streaming a request body or
   1.158 +  certain POST fields (bigger chunks will be fragmented automatically)
   1.159 +- minimum_output_chunk_size: minimum size for a chunk when sending a response
   1.160 +  body (smaller chunks will be buffered and concatenated with future data;
   1.161 +  ignored when request:flush() is called)
   1.162 +- static_headers: a set of headers to be included in every HTTP response
   1.163 +  (may be a string, a table or strings, or a table of key-value pairs)
   1.164 +
   1.165 +The callback function receives a single request object as argument, which is
   1.166 +described below.
   1.167 +
   1.168 +
   1.169 +### request.body
   1.170 +
   1.171 +The request body (without headers) as a string. Accessing this value makes
   1.172 +further access to request.post_params and request.post_params_list, or
   1.173 +invocation of request:stream_request_body(...) impossible.
   1.174 +
   1.175 +
   1.176 +### request.cookies
   1.177 +
   1.178 +A table with all cookies sent by the client.
   1.179 +
   1.180 +
   1.181 +### request.defer_reading()
   1.182 +
   1.183 +Disables automatic request body processing on write. Can be called before
   1.184 +sending a HTTP status code to send a response before the request has been fully
   1.185 +received.
   1.186 +
   1.187 +CAUTION: Responding to a request before the request body has been processed may
   1.188 +lead to a deadlock if the browser does not process the response while trying to
   1.189 +send the request. Therefore, this function should only be used if:
   1.190 +
   1.191 +- the TCP stack has enough buffer space for the response (i.e. if the response
   1.192 +  is small enough), and if
   1.193 +- a timer is used to cancel the response in case of a deadlock.
   1.194 +
   1.195 +It is recommended to not use this function unless certain performance tweaks
   1.196 +are desired.
   1.197 +
   1.198 +
   1.199 +### request:finish()
   1.200 +
   1.201 +Finishes and flushes a HTTP response. May be called multiple times. An
   1.202 +HTTP status, all headers, and the response body (if applicable) must have been
   1.203 +previously sent. After calling this method, no further data may be written.
   1.204 +
   1.205 +
   1.206 +### request:finish_headers()
   1.207 +
   1.208 +Finishes and flushes the HTTP response header section. May be called multiple
   1.209 +times, as long as the request is not finished completely. This method is
   1.210 +automatically invoked if the application is beginning to send a response body.
   1.211 +After calling this method, no further headers may be sent.
   1.212 +
   1.213 +
   1.214 +### request:flush()
   1.215 +
   1.216 +Flushes any pending output data. Note: In order to mark the end of a response
   1.217 +body, it is required to call request:finish().
   1.218 +
   1.219 +
   1.220 +### request.get_params
   1.221 +
   1.222 +A table that maps field names to their corresponding GET value. If there are
   1.223 +several GET values with the given field name, then the first value is used.
   1.224 +
   1.225 +
   1.226 +### request.get_params_list
   1.227 +
   1.228 +A table that maps field names to a sequence of their corresponding GET values.
   1.229 +
   1.230 +
   1.231 +### request.headers
   1.232 +
   1.233 +A table that maps (case-insensitively) a HTTP header field name to a sequence
   1.234 +of values. One entry is created for every occurrence of a header line with the
   1.235 +given field name).
   1.236 +
   1.237 +
   1.238 +### request.headers_csv_string
   1.239 +
   1.240 +A table that maps (case-insensitively) a HTTP header field name to a comma
   1.241 +separated string. Multiple occurrences of the header with the given field name
   1.242 +are automatically merged into the comma separated string.
   1.243 +
   1.244 +
   1.245 +### request.headers_csv_table
   1.246 +
   1.247 +A table that maps (case-insensitively) a HTTP header field name to a sequence
   1.248 +of values. One entry is created for every comma separated value of each header
   1.249 +with the given field name.
   1.250 +
   1.251 +
   1.252 +### request.headers_flags
   1.253 +
   1.254 +A table that maps (case-insensitively) a HTTP header field name to another
   1.255 +table which (again case-insensitively) maps a string to a boolean, depending on
   1.256 +whether this string occurred in the list of comma separated values of one
   1.257 +header line with the given field name that was the key in the first table.
   1.258 +
   1.259 +
   1.260 +### request.headers_value
   1.261 +
   1.262 +A table that maps (case-insensitively) a HTTP header field name to a value. If
   1.263 +multiple header lines with the given field name have been received, false is
   1.264 +used as value.
   1.265 +
   1.266 +
   1.267 +### request.method
   1.268 +
   1.269 +The HTTP request method, e.g. "HEAD", "GET", or "POST".
   1.270 +
   1.271 +
   1.272 +### request.path
   1.273 +
   1.274 +The requested path, e.g. "/index.html", without the query part (that starts
   1.275 +with a question mark, see request.query and request.url).
   1.276 +
   1.277 +
   1.278 +### request.post_metadata
   1.279 +
   1.280 +Only set for multipart/form-data POST requests. A table that maps field names
   1.281 +to their corresponding POST metadata table which contains two entries:
   1.282 +"file_name" and "content_type". If there are several POST values with the given
   1.283 +field name, then the first value/file is used.
   1.284 +
   1.285 +
   1.286 +### request.post_metadata_list
   1.287 +
   1.288 +Only set for multipart/form-data POST requests. A table that maps field names
   1.289 +to a sequence with their corresponding POST metadata tables. Needed if multiple
   1.290 +files are uploaded with the same field name.
   1.291 +
   1.292 +
   1.293 +### request.post_params
   1.294 +
   1.295 +A table that maps field names to their corresponding POST value. If there are
   1.296 +several POST values with the given field name, then the first value is used.
   1.297 +
   1.298 +
   1.299 +### request.post_params_list
   1.300 +
   1.301 +A table that maps field names to a sequence of their corresponding POST values.
   1.302 +
   1.303 +
   1.304 +### request.query
   1.305 +
   1.306 +Query part of request path without the leading question mark, e.g. "a=b&c=d" if
   1.307 +request.path is "index.html?a=b&c=d". The data is automatically parsed and made
   1.308 +available through request.get_params and request.get_params_list.
   1.309 +
   1.310 +
   1.311 +### request:process_request_body()
   1.312 +
   1.313 +Starts processing the request body (if existent) to set the values
   1.314 +request.post_params, request.post_params_list, request.post_metadata, and
   1.315 +and request.post_metadata_list and/or to call POST field stream handlers that
   1.316 +have been previously registered with request:stream_post_param(...) or
   1.317 +request:stream_post_params(...).
   1.318 +
   1.319 +This method gets invoked automatically when the POST param tables
   1.320 +(request.post_params, etc.) are accessed, or if a response is sent (to avoid
   1.321 +deadlocks with the webbrowser). (Note: Automatic request body processing on
   1.322 +write may be disabled by calling request:defer_reading().)
   1.323 +
   1.324 +After this method returned, all registered POST field stream handlers have
   1.325 +received all data. Registration of other POST field stream handlers is not
   1.326 +possible after this method has been called (or after request.post_params_list
   1.327 +or request.post_params have been accessed).
   1.328 +
   1.329 +
   1.330 +### request:send_data(...)
   1.331 +
   1.332 +Sends data as response body. All arguments are converted via tostring(...) and
   1.333 +concatenated. May be called multiple times until the request has been finished
   1.334 +by calling request:finish().
   1.335 +
   1.336 +If the request method (see request.method) is "HEAD", then calls to
   1.337 +request:send_data(...) are automatically ignored.
   1.338 +
   1.339 +
   1.340 +### request:send_header(key, value)
   1.341 +
   1.342 +Sends a HTTP response header that consists of the given key and the given
   1.343 +value. Note: Key and value must be provided as separate arguments. Before any
   1.344 +headers can be sent, a HTTP status must have been set with
   1.345 +request:send_status(status_string).
   1.346 +
   1.347 +
   1.348 +### request:send_status(status_string)
   1.349 +
   1.350 +Sends a HTTP response status that is given as a string consisting of a 3-digit
   1.351 +number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
   1.352 +function must be called once before any headers or response body data may be
   1.353 +sent.
   1.354 +
   1.355 +
   1.356 +### request.socket
   1.357 +
   1.358 +The underlaying socket. Can be used to force a TCP RST, etc.
   1.359 +
   1.360 +
   1.361 +### request:stream_post_param(field_name, callback)
   1.362 +
   1.363 +Registers a stream handler for the given POST parameter. The callback function
   1.364 +will be called in the following manner:
   1.365 +
   1.366 +- For the initial chunk, the first chunk gets passed as first argument while a
   1.367 +  table with metadata ("field_name" and "content_type") gets passed as second
   1.368 +  argument. In case of an immediate EOF (i.e. an empty file), the passed
   1.369 +  chunk is the empty string. In all other cases the chunk has a length greater
   1.370 +  than zero.
   1.371 +- For any remaining chunks, the respective chunk gets passed as first and only
   1.372 +  argument (no metadata). Here, the chunk has always a length greater than
   1.373 +  zero.
   1.374 +- To indicate the end of the stream, the callback function is called without
   1.375 +  arguments. This also happens in case of an immediate EOF (see above).
   1.376 +
   1.377 +In case of an immediate EOF (i.e. an empty file), the callback function is thus
   1.378 +called as follows:
   1.379 +
   1.380 +- The first time with an empty string as first argument, and with the metadata
   1.381 +  as second argument.
   1.382 +- The second time without any arguments.
   1.383 +
   1.384 +
   1.385 +### request:stream_post_params(pattern, callback)
   1.386 +
   1.387 +Same as request:stream_post_param(...) but providing a string pattern to match
   1.388 +multiple field names (e.g. "^file_[0-9]+$").
   1.389 +
   1.390 +
   1.391 +### request:stream_request_body(callback)
   1.392 +
   1.393 +Start streaming of request body. For each chunk of the request body, the
   1.394 +callback function is called with the corresponding chunk. End of data is
   1.395 +indicated through return of request:stream_request_body(...) (not by calling
   1.396 +the callback without arguments).
   1.397 +
   1.398 +
   1.399 +### request.url
   1.400 +
   1.401 +The requested URL. This value is automatically split up into request.path and
   1.402 +request.query using the question mark as delimiter. The
   1.403 +
   1.404 +