view reference.txt @ 7:4d7551c962d5

New method request:send_text_status_response(...) that was previously only available internally as error_response(...) function
author jbe
date Thu Jan 29 01:33:00 2015 +0100 (2015-01-29)
parents f6d3b3f70dab
children 7e6faff049c3
line source
2 Moonbridge reference
3 ====================
7 Global function listen(...)
8 ---------------------------
10 This function initializes the Moonbridge Network Server. It may be called
11 multiple times. However, it is not allowed to register additional listeners by
12 calling listen(...) from a "prepare", "connect", or "finish" handler.
14 See file "example.lua" for parametrization of the listen(...) function.
16 Warning: Moonbridge will fork the Lua environment to handle parallel requests.
17 Functions provided as "prepare", "connect", and "finish" handlers may access
18 global variables, but for every child process these global variables will not
19 be shared! If you require a global state, a DBMS, cache server, or similar is
20 necessary.
24 Socket object passed to "connect" handler
25 -----------------------------------------
27 For every incoming connection, the registered "connect" handler is called with
28 a single socket object as argument, which is described below:
31 ### socket:cancel()
33 Closes the socket connection by sending a TCP RST package if possible to
34 indicate error condition.
36 Warning: Previously sent (and flushed) data may be lost during transmission.
39 ### socket:close(timeout)
41 Closes the socket connection (input and output stream) by flushing all data and
42 sending a TCP FIN package. Performs no operation if stream has already been
43 closed.
45 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
46 depending on the particular operating system used. All pending input data
47 should have been read before calling socket:close().
49 The optional timeout parameter may be used to wait until all data has been sent
50 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
51 happens first. A timeout value of 0 or nil causes immediate return and sending
52 of pending data in background (recommended).
55 ### socket:flush()
57 Alias for socket.output:flush()
60 ### socket.input
62 Lua file handle representing the input stream of the socket connection.
63 Supports the same methods as's return values.
66 ### socket.interval
68 Set to the name of an interval timer if the "connect" handler was called due to
69 an elapsed interval timer. Otherwise nil.
72 ### socket:lines()
74 Alias for socket.input:lines()
77 ### socket.local_ip4
79 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
80 string.
83 ### socket.local_ip6
85 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
86 a string.
89 ### socket.local_tcpport
91 Local TCP port used for the connection.
94 ### socket.output
96 Lua file handle representing the output stream of the socket connection.
97 Supports the same methods as's return values.
100 ### socket:read(...)
102 Alias for socket.input:read()
105 ### socket:readuntil(terminator, maxlen)
107 Reads as many bytes until a byte equal to the terminator value occurs. An
108 optional maximum length may be specified. The terminating byte is included in
109 the return value (unless the maximum length would be exceeded).
111 Also available as :readuntil(...) method for any other Lua file handle
112 (including socket.input)
115 ### socket.remote_ip4
117 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
118 a string.
121 ### socket.remote_ip6
123 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
124 a string.
127 ### socket.remote_tcpport
129 Remote TCP port used for the connection.
132 ### socket:write(...)
134 Alias for socket.output:write(...)
138 HTTP module
139 -----------
141 The http module exports the function http.generate_handler(callback) that
142 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
143 example of invocation. A table with options may be passed either as a second
144 argument, or as a first argument preceeding the callback function (whichever is
145 more convenient).
147 The following options are supported:
149 - request_body_size_limit: maximum size of payload of HTTP request body
150 (transfer encoding is allowed to add a limited amount of extra data)
151 - chunk_size: optional default value for maximum_input_chunk_size and
152 minimum_output_chunk_size
153 - request_header_size_limit: maximum size of HTTP request headers
154 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
155 certain POST fields (bigger chunks will be fragmented automatically)
156 - minimum_output_chunk_size: minimum size for a chunk when sending a response
157 body (smaller chunks will be buffered and concatenated with future data;
158 ignored when request:flush() is called)
159 - static_headers: a set of headers to be included in every HTTP response
160 (may be a string, a table or strings, or a table of key-value pairs)
162 The callback function receives a single request object as argument, which is
163 described below.
166 ### request.body
168 The request body (without headers) as a string. Accessing this value makes
169 further access to request.post_params and request.post_params_list, or
170 invocation of request:stream_request_body(...) impossible.
173 ### request.cookies
175 A table with all cookies sent by the client.
178 ### request.defer_reading()
180 Disables automatic request body processing on write. Can be called before
181 sending a HTTP status code to send a response before the request has been fully
182 received.
184 CAUTION: Responding to a request before the request body has been processed may
185 lead to a deadlock if the browser does not process the response while trying to
186 send the request. Therefore, this function should only be used if:
188 - the TCP stack has enough buffer space for the response (i.e. if the response
189 is small enough), and if
190 - a timer is used to cancel the response in case of a deadlock.
192 It is recommended to not use this function unless certain performance tweaks
193 are desired.
196 ### request:finish()
198 Finishes and flushes a HTTP response. May be called multiple times. An
199 HTTP status, all headers, and the response body (if applicable) must have been
200 previously sent. After calling this method, no further data may be written.
203 ### request:finish_headers()
205 Finishes and flushes the HTTP response header section. May be called multiple
206 times, as long as the request is not finished completely. This method is
207 automatically invoked if the application is beginning to send a response body.
208 After calling this method, no further headers may be sent.
211 ### request:flush()
213 Flushes any pending output data. Note: In order to mark the end of a response
214 body, it is required to call request:finish().
217 ### request.get_params
219 A table that maps field names to their corresponding GET value. If there are
220 several GET values with the given field name, then the first value is used.
223 ### request.get_params_list
225 A table that maps field names to a sequence of their corresponding GET values.
228 ### request.headers
230 A table that maps (case-insensitively) a HTTP header field name to a sequence
231 of values. One entry is created for every occurrence of a header line with the
232 given field name).
235 ### request.headers_csv_string
237 A table that maps (case-insensitively) a HTTP header field name to a comma
238 separated string. Multiple occurrences of the header with the given field name
239 are automatically merged into the comma separated string.
242 ### request.headers_csv_table
244 A table that maps (case-insensitively) a HTTP header field name to a sequence
245 of values. One entry is created for every comma separated value of each header
246 with the given field name.
249 ### request.headers_flags
251 A table that maps (case-insensitively) a HTTP header field name to another
252 table which (again case-insensitively) maps a string to a boolean, depending on
253 whether this string occurred in the list of comma separated values of one
254 header line with the given field name that was the key in the first table.
257 ### request.headers_value
259 A table that maps (case-insensitively) a HTTP header field name to a value. If
260 multiple header lines with the given field name have been received, false is
261 used as value.
264 ### request.method
266 The HTTP request method, e.g. "HEAD", "GET", or "POST".
269 ### request.path
271 The requested path, e.g. "/index.html", without the query part (that starts
272 with a question mark, see request.query and request.url).
275 ### request.post_metadata
277 Only set for multipart/form-data POST requests. A table that maps field names
278 to their corresponding POST metadata table which contains two entries:
279 "file_name" and "content_type". If there are several POST values with the given
280 field name, then the first value/file is used.
283 ### request.post_metadata_list
285 Only set for multipart/form-data POST requests. A table that maps field names
286 to a sequence with their corresponding POST metadata tables. Needed if multiple
287 files are uploaded with the same field name.
290 ### request.post_params
292 A table that maps field names to their corresponding POST value. If there are
293 several POST values with the given field name, then the first value is used.
296 ### request.post_params_list
298 A table that maps field names to a sequence of their corresponding POST values.
301 ### request.query
303 Query part of request path without the leading question mark, e.g. "a=b&c=d" if
304 request.path is "index.html?a=b&c=d". The data is automatically parsed and made
305 available through request.get_params and request.get_params_list.
308 ### request:process_request_body()
310 Starts processing the request body (if existent) to set the values
311 request.post_params, request.post_params_list, request.post_metadata, and
312 and request.post_metadata_list and/or to call POST field stream handlers that
313 have been previously registered with request:stream_post_param(...) or
314 request:stream_post_params(...).
316 This method gets invoked automatically when the POST param tables
317 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
318 deadlocks with the webbrowser). (Note: Automatic request body processing on
319 write may be disabled by calling request:defer_reading().)
321 After this method returned, all registered POST field stream handlers have
322 received all data. Registration of other POST field stream handlers is not
323 possible after this method has been called (or after request.post_params_list
324 or request.post_params have been accessed).
327 ### request:send_data(...)
329 Sends data as response body. All arguments are converted via tostring(...) and
330 concatenated. May be called multiple times until the request has been finished
331 by calling request:finish().
333 If the request method (see request.method) is "HEAD", then calls to
334 request:send_data(...) are automatically ignored.
337 ### request:send_header(key, value)
339 Sends a HTTP response header that consists of the given key and the given
340 value. Note: Key and value must be provided as separate arguments. Before any
341 headers can be sent, a HTTP status must have been set with
342 request:send_status(status_string).
345 ### request:send_status(status_string)
347 Sends a HTTP response status that is given as a string consisting of a 3-digit
348 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
349 function must be called once before any headers or response body data may be
350 sent.
353 ### request.socket
355 The underlaying socket. Can be used to force a TCP RST, etc.
358 ### request:stream_post_param(field_name, callback)
360 Registers a stream handler for the given POST parameter. The callback function
361 will be called in the following manner:
363 - For the initial chunk, the first chunk gets passed as first argument while a
364 table with metadata ("field_name" and "content_type") gets passed as second
365 argument. In case of an immediate EOF (i.e. an empty file), the passed
366 chunk is the empty string. In all other cases the chunk has a length greater
367 than zero.
368 - For any remaining chunks, the respective chunk gets passed as first and only
369 argument (no metadata). Here, the chunk has always a length greater than
370 zero.
371 - To indicate the end of the stream, the callback function is called without
372 arguments. This also happens in case of an immediate EOF (see above).
374 In case of an immediate EOF (i.e. an empty file), the callback function is thus
375 called as follows:
377 - The first time with an empty string as first argument, and with the metadata
378 as second argument.
379 - The second time without any arguments.
382 ### request:stream_post_params(pattern, callback)
384 Same as request:stream_post_param(...) but providing a string pattern to match
385 multiple field names (e.g. "^file_[0-9]+$").
388 ### request:stream_request_body(callback)
390 Start streaming of request body. For each chunk of the request body, the
391 callback function is called with the corresponding chunk. End of data is
392 indicated through return of request:stream_request_body(...) (not by calling
393 the callback without arguments).
396 ### request:send_text_status_response(status_string, text)
398 Sends a HTTP status plus a response body of content-type "text/plain" and
399 finishes the request using request:finish(). The status_string has to be
400 provided in the same format as expected by request:send_status(...) and will
401 be included in the response body as plain text. The additional second "text"
402 argument will be appended to the reponse body (separated by an empty line) if
403 given.
406 ### request.url
408 The requested URL. This value is automatically split up into request.path and
409 request.query using the question mark as delimiter. The

Impressum / About Us