jbe@0: jbe@0: Moonbridge reference jbe@0: ==================== jbe@0: jbe@0: jbe@0: jbe@52: Global function listen{...} jbe@0: --------------------------- jbe@0: jbe@0: This function initializes the Moonbridge Network Server. It may be called jbe@0: multiple times. However, it is not allowed to register additional listeners by jbe@0: calling listen(...) from a "prepare", "connect", or "finish" handler. jbe@0: jbe@0: See file "example.lua" for parametrization of the listen(...) function. jbe@0: jbe@0: Warning: Moonbridge will fork the Lua environment to handle parallel requests. jbe@0: Functions provided as "prepare", "connect", and "finish" handlers may access jbe@0: global variables, but for every child process these global variables will not jbe@0: be shared! If you require a global state, a DBMS, cache server, or similar is jbe@0: necessary. jbe@0: jbe@0: jbe@0: jbe@50: Global function timeout(...) jbe@50: ---------------------------- jbe@50: jbe@50: Calling this function with a positive number (time in seconds) sets a timer jbe@50: that kills the current process after the selected time runs out. The remaining jbe@50: time can be queried by calling this function without arguments. jbe@50: jbe@50: Calling this function with a single argument that is the number zero will jbe@50: disable the timeout. jbe@50: jbe@50: Another mode of operation is selected by passing two arguments: a time (in jbe@50: seconds) as first argument and a function as second argument. In this case, a jbe@50: sub-timer will be used to limit the execution time of the function. In case of jbe@50: timeout, the process will be killed (and the timeout function does not return). jbe@50: If the time for the sub-timer is longer than a previously set timeout (using jbe@50: the timeout(...) function with one argument), the shorter timeout (of the jbe@50: previous call of timeout(...)) will have precedence. jbe@50: jbe@52: Timers are also automatically reset (disabled) when a handler (prepare handler jbe@52: or connect handler) returns. To shutdown processes after a certain time waiting jbe@52: for a new request, use the idle_time parameter of the listen function. jbe@52: jbe@50: jbe@50: jbe@0: Socket object passed to "connect" handler jbe@0: ----------------------------------------- jbe@0: jbe@0: For every incoming connection, the registered "connect" handler is called with jbe@0: a single socket object as argument, which is described below: jbe@0: jbe@0: jbe@0: ### socket:cancel() jbe@0: jbe@0: Closes the socket connection by sending a TCP RST package if possible to jbe@43: indicate error condition. Returns true on success, or nil plus error message in jbe@43: case of an I/O error. Using this method on sockets that have already been jbe@43: closed (or canceled) will throw an error. jbe@0: jbe@0: Warning: Previously sent (and flushed) data may be lost during transmission. jbe@0: jbe@0: jbe@0: ### socket:close(timeout) jbe@0: jbe@0: Closes the socket connection (input and output stream) by flushing all data and jbe@43: sending a TCP FIN package. Returns true on success, or nil plus error message jbe@43: in case of an I/O error. Using this method on sockets that have already been jbe@43: closed (or canceled) will throw an error. jbe@0: jbe@0: Warning: Pending data on the input stream may cause connection aborts (TCP RST) jbe@0: depending on the particular operating system used. All pending input data jbe@0: should have been read before calling socket:close(). jbe@0: jbe@0: The optional timeout parameter may be used to wait until all data has been sent jbe@0: out, or until the timeout elapses (in which case a TCP RST is sent) whichever jbe@0: happens first. A timeout value of 0 or nil causes immediate return and sending jbe@0: of pending data in background (recommended). jbe@0: jbe@0: jbe@0: ### socket:flush() jbe@0: jbe@0: Alias for socket.output:flush() jbe@0: jbe@0: jbe@0: ### socket.input jbe@0: jbe@0: Lua file handle representing the input stream of the socket connection. jbe@0: Supports the same methods as io.open()'s return values. jbe@0: jbe@0: jbe@0: ### socket.interval jbe@0: jbe@0: Set to the name of an interval timer if the "connect" handler was called due to jbe@0: an elapsed interval timer. Otherwise nil. jbe@0: jbe@0: jbe@0: ### socket:lines() jbe@0: jbe@0: Alias for socket.input:lines() jbe@0: jbe@0: jbe@0: ### socket.local_ip4 jbe@0: jbe@0: Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a jbe@0: string. jbe@0: jbe@0: jbe@0: ### socket.local_ip6 jbe@0: jbe@0: Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of jbe@0: a string. jbe@0: jbe@0: jbe@0: ### socket.local_tcpport jbe@0: jbe@0: Local TCP port used for the connection. jbe@0: jbe@0: jbe@0: ### socket.output jbe@0: jbe@0: Lua file handle representing the output stream of the socket connection. jbe@0: Supports the same methods as io.open()'s return values. jbe@0: jbe@0: jbe@0: ### socket:read(...) jbe@0: jbe@0: Alias for socket.input:read() jbe@0: jbe@0: jbe@0: ### socket:readuntil(terminator, maxlen) jbe@0: jbe@0: Reads as many bytes until a byte equal to the terminator value occurs. An jbe@0: optional maximum length may be specified. The terminating byte is included in jbe@43: the return value (unless the maximum length would be exceeded). On EOF, nil is jbe@43: returned. In case of an I/O error, nil (as first result value) plus an error jbe@43: message (as second result value) is returned. jbe@0: jbe@43: This method is also available as :readuntil(...) for any other Lua file handle jbe@43: (including socket.input). jbe@0: jbe@0: jbe@0: ### socket.remote_ip4 jbe@0: jbe@0: Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of jbe@0: a string. jbe@0: jbe@0: jbe@0: ### socket.remote_ip6 jbe@0: jbe@0: Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of jbe@0: a string. jbe@0: jbe@0: jbe@0: ### socket.remote_tcpport jbe@0: jbe@0: Remote TCP port used for the connection. jbe@0: jbe@0: jbe@0: ### socket:write(...) jbe@0: jbe@0: Alias for socket.output:write(...) jbe@0: jbe@0: jbe@0: jbe@0: HTTP module jbe@0: ----------- jbe@0: jbe@0: The http module exports the function http.generate_handler(callback) that jbe@0: converts an HTTP handler to a "connect" handler. See file "example.lua" for an jbe@0: example of invocation. A table with options may be passed either as a second jbe@0: argument, or as a first argument preceeding the callback function (whichever is jbe@0: more convenient). jbe@0: jbe@0: The following options are supported: jbe@0: jbe@0: - request_body_size_limit: maximum size of payload of HTTP request body jbe@0: (transfer encoding is allowed to add a limited amount of extra data) jbe@0: - chunk_size: optional default value for maximum_input_chunk_size and jbe@0: minimum_output_chunk_size jbe@0: - request_header_size_limit: maximum size of HTTP request headers jbe@0: - maximum_input_chunk_size: maximum chunk size when streaming a request body or jbe@0: certain POST fields (bigger chunks will be fragmented automatically) jbe@0: - minimum_output_chunk_size: minimum size for a chunk when sending a response jbe@0: body (smaller chunks will be buffered and concatenated with future data; jbe@0: ignored when request:flush() is called) jbe@0: - static_headers: a set of headers to be included in every HTTP response jbe@0: (may be a string, a table or strings, or a table of key-value pairs) jbe@0: jbe@0: The callback function receives a single request object as argument, which is jbe@0: described below. jbe@0: jbe@0: jbe@0: ### request.body jbe@0: jbe@0: The request body (without headers) as a string. Accessing this value makes jbe@0: further access to request.post_params and request.post_params_list, or jbe@0: invocation of request:stream_request_body(...) impossible. jbe@0: jbe@0: jbe@60: ### request:close_after_finish() jbe@60: jbe@60: Closes the connection after answering the request. jbe@60: jbe@60: This method can only be called before the HTTP response header section has been jbe@60: finished (i.e. before request:finish_headers(), request:send_data(...), or jbe@60: request:finish() were called), but it may be called before a status code has jbe@60: been sent using request:send_status(...). jbe@60: jbe@60: A corresponding "Connection: close" header is automatically sent. jbe@60: jbe@60: jbe@0: ### request.cookies jbe@0: jbe@0: A table with all cookies sent by the client. jbe@0: jbe@0: jbe@0: ### request.defer_reading() jbe@0: jbe@0: Disables automatic request body processing on write. Can be called before jbe@0: sending a HTTP status code to send a response before the request has been fully jbe@0: received. jbe@0: jbe@0: CAUTION: Responding to a request before the request body has been processed may jbe@0: lead to a deadlock if the browser does not process the response while trying to jbe@0: send the request. Therefore, this function should only be used if: jbe@0: jbe@0: - the TCP stack has enough buffer space for the response (i.e. if the response jbe@0: is small enough), and if jbe@0: - a timer is used to cancel the response in case of a deadlock. jbe@0: jbe@0: It is recommended to not use this function unless certain performance tweaks jbe@0: are desired. jbe@0: jbe@0: jbe@50: ### request.faulty jbe@50: jbe@50: Normally set to false. In case of a read or write error on the client jbe@50: connection, this value is set to true before a Lua error is raised. jbe@50: jbe@50: A faulty request handle must not be used, or another Lua error will be raised. jbe@50: jbe@50: jbe@0: ### request:finish() jbe@0: jbe@0: Finishes and flushes a HTTP response. May be called multiple times. An jbe@0: HTTP status, all headers, and the response body (if applicable) must have been jbe@0: previously sent. After calling this method, no further data may be written. jbe@0: jbe@0: jbe@0: ### request:finish_headers() jbe@0: jbe@0: Finishes and flushes the HTTP response header section. May be called multiple jbe@0: times, as long as the request is not finished completely. This method is jbe@0: automatically invoked if the application is beginning to send a response body. jbe@0: After calling this method, no further headers may be sent. jbe@0: jbe@0: jbe@0: ### request:flush() jbe@0: jbe@0: Flushes any pending output data. Note: In order to mark the end of a response jbe@0: body, it is required to call request:finish(). jbe@0: jbe@0: jbe@0: ### request.get_params jbe@0: jbe@0: A table that maps field names to their corresponding GET value. If there are jbe@0: several GET values with the given field name, then the first value is used. jbe@0: jbe@35: Note: May be implemented through metamethods, but does support iteration jbe@35: through pairs(...). jbe@35: jbe@0: jbe@0: ### request.get_params_list jbe@0: jbe@0: A table that maps field names to a sequence of their corresponding GET values. jbe@0: jbe@35: Note: May be implemented through metamethods, but does support iteration jbe@35: through pairs(...). jbe@35: jbe@0: jbe@0: ### request.headers jbe@0: jbe@0: A table that maps (case-insensitively) a HTTP header field name to a sequence jbe@0: of values. One entry is created for every occurrence of a header line with the jbe@0: given field name). jbe@0: jbe@0: jbe@0: ### request.headers_csv_string jbe@0: jbe@0: A table that maps (case-insensitively) a HTTP header field name to a comma jbe@0: separated string. Multiple occurrences of the header with the given field name jbe@0: are automatically merged into the comma separated string. jbe@0: jbe@0: jbe@0: ### request.headers_csv_table jbe@0: jbe@0: A table that maps (case-insensitively) a HTTP header field name to a sequence jbe@0: of values. One entry is created for every comma separated value of each header jbe@0: with the given field name. jbe@0: jbe@0: jbe@0: ### request.headers_flags jbe@0: jbe@0: A table that maps (case-insensitively) a HTTP header field name to another jbe@0: table which (again case-insensitively) maps a string to a boolean, depending on jbe@0: whether this string occurred in the list of comma separated values of one jbe@0: header line with the given field name that was the key in the first table. jbe@0: jbe@0: jbe@0: ### request.headers_value jbe@0: jbe@0: A table that maps (case-insensitively) a HTTP header field name to a value. If jbe@0: multiple header lines with the given field name have been received, false is jbe@0: used as value. jbe@0: jbe@0: jbe@0: ### request.method jbe@0: jbe@0: The HTTP request method, e.g. "HEAD", "GET", or "POST". jbe@0: jbe@0: jbe@0: ### request.path jbe@0: jbe@10: The requested path without a leading slash and without the query part (e.g. jbe@10: "index.html" if "/index.html?a=b&c=d" has been requested). For the query part, jbe@10: see request.query. jbe@10: jbe@10: This value will be nil if (and only if) the request method is "OPTIONS" with a jbe@10: request target equal to "*" (see also asterisk-form of request-target in jbe@10: section 5.3.4 in RFC 7230). jbe@0: jbe@0: jbe@0: ### request.post_metadata jbe@0: jbe@0: Only set for multipart/form-data POST requests. A table that maps field names jbe@0: to their corresponding POST metadata table which contains two entries: jbe@0: "file_name" and "content_type". If there are several POST values with the given jbe@0: field name, then the first value/file is used. jbe@0: jbe@0: jbe@0: ### request.post_metadata_list jbe@0: jbe@0: Only set for multipart/form-data POST requests. A table that maps field names jbe@0: to a sequence with their corresponding POST metadata tables. Needed if multiple jbe@0: files are uploaded with the same field name. jbe@0: jbe@0: jbe@0: ### request.post_params jbe@0: jbe@0: A table that maps field names to their corresponding POST value. If there are jbe@0: several POST values with the given field name, then the first value is used. jbe@0: jbe@35: Note: May be implemented through metamethods, but does support iteration jbe@35: through pairs(...). jbe@35: jbe@0: jbe@0: ### request.post_params_list jbe@0: jbe@0: A table that maps field names to a sequence of their corresponding POST values. jbe@0: jbe@35: Note: May be implemented through metamethods, but does support iteration jbe@35: through pairs(...). jbe@35: jbe@0: jbe@0: ### request.query jbe@0: jbe@12: Query part of the request target including the leading question mark, e.g. jbe@12: "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is jbe@10: automatically parsed and made available through request.get_params and jbe@10: request.get_params_list. jbe@10: jbe@10: If there is no query part given in the request target, then this string is jbe@10: the empty string. This value will be nil if (and only if) the request method jbe@10: is "OPTIONS" with a request target equal to "*" (see also asterisk-form of jbe@10: request-target in section 5.3.4 in RFC 7230). jbe@0: jbe@0: jbe@0: ### request:process_request_body() jbe@0: jbe@0: Starts processing the request body (if existent) to set the values jbe@0: request.post_params, request.post_params_list, request.post_metadata, and jbe@0: and request.post_metadata_list and/or to call POST field stream handlers that jbe@0: have been previously registered with request:stream_post_param(...) or jbe@0: request:stream_post_params(...). jbe@0: jbe@0: This method gets invoked automatically when the POST param tables jbe@0: (request.post_params, etc.) are accessed, or if a response is sent (to avoid jbe@0: deadlocks with the webbrowser). (Note: Automatic request body processing on jbe@0: write may be disabled by calling request:defer_reading().) jbe@0: jbe@0: After this method returned, all registered POST field stream handlers have jbe@0: received all data. Registration of other POST field stream handlers is not jbe@0: possible after this method has been called (or after request.post_params_list jbe@0: or request.post_params have been accessed). jbe@0: jbe@0: jbe@0: ### request:send_data(...) jbe@0: jbe@0: Sends data as response body. All arguments are converted via tostring(...) and jbe@0: concatenated. May be called multiple times until the request has been finished jbe@0: by calling request:finish(). jbe@0: jbe@0: If the request method (see request.method) is "HEAD", then calls to jbe@0: request:send_data(...) are automatically ignored. jbe@0: jbe@0: jbe@0: ### request:send_header(key, value) jbe@0: jbe@0: Sends a HTTP response header that consists of the given key and the given jbe@0: value. Note: Key and value must be provided as separate arguments. Before any jbe@0: headers can be sent, a HTTP status must have been set with jbe@0: request:send_status(status_string). jbe@0: jbe@0: jbe@0: ### request:send_status(status_string) jbe@0: jbe@0: Sends a HTTP response status that is given as a string consisting of a 3-digit jbe@0: number and an explanatory string, e.g. "200 OK" or "404 Not Found". This jbe@0: function must be called once before any headers or response body data may be jbe@0: sent. jbe@0: jbe@0: jbe@0: ### request.socket jbe@0: jbe@0: The underlaying socket. Can be used to force a TCP RST, etc. jbe@0: jbe@0: jbe@0: ### request:stream_post_param(field_name, callback) jbe@0: jbe@0: Registers a stream handler for the given POST parameter. The callback function jbe@0: will be called in the following manner: jbe@0: jbe@0: - For the initial chunk, the first chunk gets passed as first argument while a jbe@0: table with metadata ("field_name" and "content_type") gets passed as second jbe@0: argument. In case of an immediate EOF (i.e. an empty file), the passed jbe@0: chunk is the empty string. In all other cases the chunk has a length greater jbe@0: than zero. jbe@0: - For any remaining chunks, the respective chunk gets passed as first and only jbe@0: argument (no metadata). Here, the chunk has always a length greater than jbe@0: zero. jbe@0: - To indicate the end of the stream, the callback function is called without jbe@0: arguments. This also happens in case of an immediate EOF (see above). jbe@0: jbe@0: In case of an immediate EOF (i.e. an empty file), the callback function is thus jbe@0: called as follows: jbe@0: jbe@0: - The first time with an empty string as first argument, and with the metadata jbe@0: as second argument. jbe@0: - The second time without any arguments. jbe@0: jbe@0: jbe@0: ### request:stream_post_params(pattern, callback) jbe@0: jbe@0: Same as request:stream_post_param(...) but providing a string pattern to match jbe@0: multiple field names (e.g. "^file_[0-9]+$"). jbe@0: jbe@0: jbe@0: ### request:stream_request_body(callback) jbe@0: jbe@0: Start streaming of request body. For each chunk of the request body, the jbe@0: callback function is called with the corresponding chunk. End of data is jbe@0: indicated through return of request:stream_request_body(...) (not by calling jbe@0: the callback without arguments). jbe@0: jbe@44: The function may be called with nil instead of a callback function. In this jbe@44: case, the request body is read and discarded. Only if nil is passed instead of jbe@44: a callback, then the function may also be invoked when the request body has jbe@44: already been read and/or processed. In the latter case, the function performs jbe@44: no operation. jbe@0: jbe@44: