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@94: ### socket:close() jbe@0: jbe@0: Closes the socket connection (input and output stream) by flushing all data and jbe@94: sending a TCP FIN packet. jbe@91: jbe@91: Returns true on success, or nil plus error message in case of an I/O error. jbe@91: Using this method on sockets that have already been closed (or reset) will jbe@91: throw an error. jbe@0: jbe@0: Warning: Pending data on the input stream may cause connection aborts (TCP RST) jbe@94: when network connections are used. All pending input data should have been read jbe@94: (or drained) before calling socket:close(). Use socket:finish() to send a jbe@94: TCP FIN packet to the peer before waiting for EOF from the peer. jbe@91: jbe@91: jbe@91: ### socket:drain(maxlen, terminator) jbe@0: jbe@91: Same as socket:read(maxlen, terminator), but discards the input and returns the jbe@143: number of discarded bytes (as first return value) and the status code ("term", jbe@143: "maxlen", "eof" as second return value). jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. jbe@0: jbe@0: jbe@144: ### socket:drain_call(waitfunc, maxlen, terminator) jbe@144: jbe@144: Same as socket:drain(maxlen, terminator), but calls waitfunc(socket, "r") (in jbe@144: an infinite loop) as long as the reading is blocked. jbe@144: jbe@144: jbe@91: ### socket:drain_nb(maxlen, terminator) jbe@0: jbe@143: Same as socket:drain(maxlen, terminator), but non-blocking. The status code jbe@143: (which is returned as second return value) may therefore be "term", "maxlen", jbe@143: "eof", or "block". jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. jbe@91: jbe@0: jbe@144: ### socket:drain_yield(maxlen, terminator) jbe@144: jbe@144: Alias for socket:drain_call(coroutine.yield, maxlen, terminator) jbe@144: jbe@144: jbe@94: ### socket:finish() jbe@94: jbe@94: Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are jbe@94: still possible. When there is no more input data to be read, the connection jbe@94: should finally be closed with socket:close(). jbe@94: jbe@94: In case of local sockets (Unix Domain Sockets), socket:finish() simply closes jbe@94: the underlying socket and emulates EOF on subsequent reads. Also in this case, jbe@94: the connection should be finally closed with socket:close(). jbe@94: jbe@94: jbe@91: ### socket:flush(...) jbe@91: jbe@91: Same as socket:write(...) but additionally flushes the socket (i.e. all pending jbe@91: data is passed to the operating system). jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. On success, the socket userdata object is jbe@91: returned. jbe@91: jbe@0: jbe@145: ### socket:flush_call(waitfunc, ...) jbe@145: jbe@152: Same as socket:flush(...), but calls waitfunc() (in an infinite loop) as long jbe@152: as the writing is blocked. jbe@145: jbe@145: jbe@91: ### socket:flush_nb(...) jbe@91: jbe@91: Same as socket:write_nb(...) but additionally flushes the socket (i.e. all jbe@91: pending data is passed to the operating system). The total number of bytes that jbe@91: could not be passed yet to the operating system is returned. Zero is returned jbe@91: if all data could be flushed out. jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. jbe@0: jbe@0: jbe@145: ### socket:flush_yield(...) jbe@145: jbe@145: Alias for socket:flush_call(coroutine.yield, ...) jbe@145: jbe@145: 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.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@91: ### socket:read(maxlen, terminator) jbe@0: jbe@143: Reads up to maxlen bytes or until an optional termination character is jbe@91: encountered (which is included in the result). The maxlen value may be nil, in jbe@91: which case there is no limit on the number of bytes read. jbe@0: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. jbe@0: jbe@143: In all other cases (including EOF), the following two values are returned: jbe@143: jbe@143: - a string containing the bytes read (first return value, may be empty string) jbe@143: - a status code equal to "term", "maxlen", or "eof" (second return value) jbe@143: jbe@143: If an EOF is encountered before all data could be read, then "eof" is returned jbe@143: as second return value. If maxlen bytes have been read and no termination jbe@143: character has been read, then "maxlen" is returned as second return value. If jbe@143: the termination character is the last character of the read string, the second jbe@143: return value will be "term". jbe@143: jbe@0: jbe@140: ### socket:read_call(waitfunc, maxlen, terminator) jbe@140: jbe@152: Same as socket:read(maxlen, terminator), but calls waitfunc() (in an infinite jbe@152: loop) as long as the reading is blocked. jbe@140: jbe@140: jbe@91: ### socket:read_nb(maxlen, terminator) jbe@91: jbe@143: Same as socket:read(maxlen, terminator), but does not block. jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. jbe@78: jbe@143: In all other cases (including EOF), the following two values are returned: jbe@143: jbe@143: - a string containing the bytes read (first return value, may be empty string) jbe@143: - a status code equal to "term", "maxlen", "eof", "block" (second return value) jbe@143: jbe@143: The status code "block" as second return value is used if the function returned jbe@143: prematurely because it would block otherwise. In this case, the first return jbe@143: value is a string that contains the bytes that could be read without blocking. jbe@143: jbe@78: jbe@140: ### socket:read_yield(maxlen, terminator) jbe@140: jbe@140: Alias for socket:read_call(coroutine.yield, maxlen, terminator) jbe@140: jbe@140: 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@91: ### socket:reset() jbe@91: jbe@91: Alias for socket:close(0). Closes the socket connection by sending a TCP RST jbe@91: packet if possible to indicate error condition. jbe@91: jbe@114: Returns true on success, or nil (as first return value) plus error message (as jbe@114: second return value) in case of an I/O error. Using this method on sockets that jbe@91: have already been closed (or reset) will throw an error. jbe@91: jbe@91: Warning: Previously sent (and flushed) data may be lost during transmission. jbe@91: jbe@91: jbe@0: ### socket:write(...) jbe@0: jbe@91: Takes a variable number of strings and sends them to the peer. The operation is jbe@91: buffered, so to actually send out the data, it is necessary to eventually call jbe@91: socket:flush(), socket:finish(), or socket:close(). jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. On success, the socket userdata object is jbe@91: returned. jbe@91: jbe@91: jbe@145: ### socket:write_call(waitfunc, ...) jbe@145: jbe@152: Same as socket:write(...), but calls waitfunc() (in an infinite loop) as long jbe@152: as the writing is blocked. jbe@145: jbe@145: jbe@91: ### socket:write_nb(...) jbe@91: jbe@91: Takes a variable number of strings and sends them to the peer. The operation is jbe@91: buffered, so to actually send out the data, it is necessary to eventually call jbe@91: socket:flush_nb(), socket:flush(), socket:finish(), or socket:close(). jbe@91: jbe@91: This function always returns immediately (i.e. it does not block). If all data jbe@91: (but a small buffered portion) could be sent out, then zero is returned. jbe@91: Otherwise, all arguments that could not be sent are stored in a buffer of jbe@91: unlimited size (up to memory capabilities) and an integer is returned that jbe@91: indicates the number of bytes currently in the buffer. jbe@91: jbe@91: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) are returned. jbe@0: jbe@0: jbe@145: ### socket:write_yield(...) jbe@145: jbe@145: Alias for socket:write_call(coroutine.yield, ...) jbe@145: jbe@145: jbe@0: jbe@98: I/O library jbe@98: ----------- jbe@98: jbe@98: The Moonbridge Network Server for Lua Applications comes with its own I/O jbe@98: library to support blocking as well as nonblocking I/O operations. jbe@98: jbe@114: All methods on an I/O handle (e.g. socket) are described in the previous jbe@114: section regarding the "socket" object. All other functions of the library are jbe@114: listed below. jbe@114: jbe@114: jbe@114: ### moonbridge_io.localconnect(path) jbe@114: jbe@114: Tries to connect to a local socket (also known as Unix Domain Socket). Returns jbe@114: a socket object on success, or nil (as first return value) plus an error jbe@114: message (as second return value) in case of error. jbe@114: jbe@114: jbe@114: ### moonbridge_io.localconnect_nb(path) jbe@114: jbe@114: Tries to connect to a local socket (also known as Unix Domain Socket). Returns jbe@114: a socket object on success, or nil (as first return value) plus an error jbe@114: message (as second return value) in case of error. jbe@114: jbe@114: Same as moonbridge_io.localconnect(path), except that this function does not jbe@114: block and immediately returns a socket object. jbe@114: jbe@114: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) may be returned. However, connection errors may also be jbe@114: reported on first read or write on the socket. jbe@114: jbe@114: jbe@114: ### moonbridge_io.locallisten(path) jbe@114: jbe@114: Attempts to create a local socket (also known as Unix Domain Socket) to accept jbe@118: incoming connections. If the file does already exist and is a socket, then it jbe@118: is deleted automatically before being re-created. jbe@114: jbe@114: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) may be returned.On success, a listener object is returned jbe@114: which supports the methods :accept(), :accept_nb(), and :close(). jbe@114: jbe@114: The method :accept() blocks until a new incoming connection is available in jbe@114: which case a socket object is returned. jbe@114: jbe@114: The method :accept_nb() works like :accept(), except that the call is jbe@114: nonblocking and returns false (plus a notice as second return value) in case no jbe@114: incoming connection is available. It is possible to wait for an incoming jbe@114: connection by including the listener object in the input_set of the jbe@114: moonbridge_io.poll(...) call. jbe@114: jbe@114: The method :close() will close the listening socket. In case of local sockets jbe@114: (Unix Domain Sockets), the socket will not be unlinked in the file system. jbe@114: jbe@114: I/O errors by the methods of the listener object are also reported by returning jbe@114: nil (as first return value) plus an error message (as second return value). jbe@114: jbe@98: jbe@106: ### moonbridge_io.poll(input_set, output_set, timeout) jbe@106: jbe@106: This function waits for at least one of the given file descriptors and/or jbe@106: I/O handles to be ready for input or output. The two sets of file descriptors jbe@106: and/or handles must contain the file descriptor or handle as a key, and a value jbe@106: which does evaluate to true. If a set is nil, it is treated as being empty. jbe@106: jbe@106: Returns true when at least one file descriptor or handle is ready for reading jbe@106: or writing respectively. Returns false (as first return value) plus a status jbe@106: message (as second return value) in case of timeout or when a signal was jbe@106: received. jbe@106: jbe@106: jbe@98: ### moonbridge_io.tcpconnect(hostname, port) jbe@98: jbe@98: Tries to open a TCP connection with the given host and TCP port number. Returns jbe@114: a socket object on success, or nil (as first return value) plus an error jbe@114: message (as second return value) in case of error. jbe@98: jbe@98: jbe@99: ### moonbridge_io.tcpconnect_nb(hostname, port) jbe@99: jbe@99: Same as moonbridge_io.tcpconnect(hostname, port), except that this function jbe@99: does not block and immediately returns a socket object. jbe@99: jbe@102: Note: The current implementation still blocks during the DNS lookup. Use a jbe@102: numeric IP address as hostname to be truly nonblocking. jbe@102: jbe@99: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) may be returned. However, connection errors may also be jbe@99: reported on first read or write on the socket. jbe@99: jbe@99: jbe@114: ### moonbridge_io.tcplisten(hostname, port) jbe@114: jbe@114: Attempts to open a TCP port for listening. To listen on the loopback interface, jbe@114: use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if jbe@114: IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or jbe@114: "0.0.0.0" (IPv4) respectively. jbe@114: jbe@114: In case of an I/O error, nil (as first return value) plus an error message (as jbe@114: second return value) may be returned. On success, a listener object is returned jbe@114: which supports the methods :accept(), :accept_nb(), and :close(). See reference jbe@114: for moonbridge.io_locallisten(...). jbe@114: jbe@114: jbe@98: 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: