moonbridge

view reference.txt @ 49:649df11b1f5a

Bugfix in local error_response function
author jbe
date Thu Mar 19 22:49:28 2015 +0100 (2015-03-19)
parents e835cda61478
children 0dd15d642124
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. Returns true on success, or nil plus error message in
35 case of an I/O error. Using this method on sockets that have already been
36 closed (or canceled) will throw an error.
38 Warning: Previously sent (and flushed) data may be lost during transmission.
41 ### socket:close(timeout)
43 Closes the socket connection (input and output stream) by flushing all data and
44 sending a TCP FIN package. Returns true on success, or nil plus error message
45 in case of an I/O error. Using this method on sockets that have already been
46 closed (or canceled) will throw an error.
48 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
49 depending on the particular operating system used. All pending input data
50 should have been read before calling socket:close().
52 The optional timeout parameter may be used to wait until all data has been sent
53 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
54 happens first. A timeout value of 0 or nil causes immediate return and sending
55 of pending data in background (recommended).
58 ### socket:flush()
60 Alias for socket.output:flush()
63 ### socket.input
65 Lua file handle representing the input stream of the socket connection.
66 Supports the same methods as io.open()'s return values.
69 ### socket.interval
71 Set to the name of an interval timer if the "connect" handler was called due to
72 an elapsed interval timer. Otherwise nil.
75 ### socket:lines()
77 Alias for socket.input:lines()
80 ### socket.local_ip4
82 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
83 string.
86 ### socket.local_ip6
88 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
89 a string.
92 ### socket.local_tcpport
94 Local TCP port used for the connection.
97 ### socket.output
99 Lua file handle representing the output stream of the socket connection.
100 Supports the same methods as io.open()'s return values.
103 ### socket:read(...)
105 Alias for socket.input:read()
108 ### socket:readuntil(terminator, maxlen)
110 Reads as many bytes until a byte equal to the terminator value occurs. An
111 optional maximum length may be specified. The terminating byte is included in
112 the return value (unless the maximum length would be exceeded). On EOF, nil is
113 returned. In case of an I/O error, nil (as first result value) plus an error
114 message (as second result value) is returned.
116 This method is also available as :readuntil(...) for any other Lua file handle
117 (including socket.input).
120 ### socket.remote_ip4
122 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
123 a string.
126 ### socket.remote_ip6
128 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
129 a string.
132 ### socket.remote_tcpport
134 Remote TCP port used for the connection.
137 ### socket:write(...)
139 Alias for socket.output:write(...)
143 HTTP module
144 -----------
146 The http module exports the function http.generate_handler(callback) that
147 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
148 example of invocation. A table with options may be passed either as a second
149 argument, or as a first argument preceeding the callback function (whichever is
150 more convenient).
152 The following options are supported:
154 - request_body_size_limit: maximum size of payload of HTTP request body
155 (transfer encoding is allowed to add a limited amount of extra data)
156 - chunk_size: optional default value for maximum_input_chunk_size and
157 minimum_output_chunk_size
158 - request_header_size_limit: maximum size of HTTP request headers
159 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
160 certain POST fields (bigger chunks will be fragmented automatically)
161 - minimum_output_chunk_size: minimum size for a chunk when sending a response
162 body (smaller chunks will be buffered and concatenated with future data;
163 ignored when request:flush() is called)
164 - static_headers: a set of headers to be included in every HTTP response
165 (may be a string, a table or strings, or a table of key-value pairs)
166 - io_error_handler: a function to be called when an I/O operation with the
167 client fails (must not return or an error will be raised automatically)
169 The callback function receives a single request object as argument, which is
170 described below.
173 ### request.body
175 The request body (without headers) as a string. Accessing this value makes
176 further access to request.post_params and request.post_params_list, or
177 invocation of request:stream_request_body(...) impossible.
180 ### request.cookies
182 A table with all cookies sent by the client.
185 ### request.defer_reading()
187 Disables automatic request body processing on write. Can be called before
188 sending a HTTP status code to send a response before the request has been fully
189 received.
191 CAUTION: Responding to a request before the request body has been processed may
192 lead to a deadlock if the browser does not process the response while trying to
193 send the request. Therefore, this function should only be used if:
195 - the TCP stack has enough buffer space for the response (i.e. if the response
196 is small enough), and if
197 - a timer is used to cancel the response in case of a deadlock.
199 It is recommended to not use this function unless certain performance tweaks
200 are desired.
203 ### request:finish()
205 Finishes and flushes a HTTP response. May be called multiple times. An
206 HTTP status, all headers, and the response body (if applicable) must have been
207 previously sent. After calling this method, no further data may be written.
210 ### request:finish_headers()
212 Finishes and flushes the HTTP response header section. May be called multiple
213 times, as long as the request is not finished completely. This method is
214 automatically invoked if the application is beginning to send a response body.
215 After calling this method, no further headers may be sent.
218 ### request:flush()
220 Flushes any pending output data. Note: In order to mark the end of a response
221 body, it is required to call request:finish().
224 ### request.get_params
226 A table that maps field names to their corresponding GET value. If there are
227 several GET values with the given field name, then the first value is used.
229 Note: May be implemented through metamethods, but does support iteration
230 through pairs(...).
233 ### request.get_params_list
235 A table that maps field names to a sequence of their corresponding GET values.
237 Note: May be implemented through metamethods, but does support iteration
238 through pairs(...).
241 ### request.headers
243 A table that maps (case-insensitively) a HTTP header field name to a sequence
244 of values. One entry is created for every occurrence of a header line with the
245 given field name).
248 ### request.headers_csv_string
250 A table that maps (case-insensitively) a HTTP header field name to a comma
251 separated string. Multiple occurrences of the header with the given field name
252 are automatically merged into the comma separated string.
255 ### request.headers_csv_table
257 A table that maps (case-insensitively) a HTTP header field name to a sequence
258 of values. One entry is created for every comma separated value of each header
259 with the given field name.
262 ### request.headers_flags
264 A table that maps (case-insensitively) a HTTP header field name to another
265 table which (again case-insensitively) maps a string to a boolean, depending on
266 whether this string occurred in the list of comma separated values of one
267 header line with the given field name that was the key in the first table.
270 ### request.headers_value
272 A table that maps (case-insensitively) a HTTP header field name to a value. If
273 multiple header lines with the given field name have been received, false is
274 used as value.
277 ### request.method
279 The HTTP request method, e.g. "HEAD", "GET", or "POST".
282 ### request.path
284 The requested path without a leading slash and without the query part (e.g.
285 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
286 see request.query.
288 This value will be nil if (and only if) the request method is "OPTIONS" with a
289 request target equal to "*" (see also asterisk-form of request-target in
290 section 5.3.4 in RFC 7230).
293 ### request.post_metadata
295 Only set for multipart/form-data POST requests. A table that maps field names
296 to their corresponding POST metadata table which contains two entries:
297 "file_name" and "content_type". If there are several POST values with the given
298 field name, then the first value/file is used.
301 ### request.post_metadata_list
303 Only set for multipart/form-data POST requests. A table that maps field names
304 to a sequence with their corresponding POST metadata tables. Needed if multiple
305 files are uploaded with the same field name.
308 ### request.post_params
310 A table that maps field names to their corresponding POST value. If there are
311 several POST values with the given field name, then the first value is used.
313 Note: May be implemented through metamethods, but does support iteration
314 through pairs(...).
317 ### request.post_params_list
319 A table that maps field names to a sequence of their corresponding POST values.
321 Note: May be implemented through metamethods, but does support iteration
322 through pairs(...).
325 ### request.query
327 Query part of the request target including the leading question mark, e.g.
328 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
329 automatically parsed and made available through request.get_params and
330 request.get_params_list.
332 If there is no query part given in the request target, then this string is
333 the empty string. This value will be nil if (and only if) the request method
334 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
335 request-target in section 5.3.4 in RFC 7230).
338 ### request:process_request_body()
340 Starts processing the request body (if existent) to set the values
341 request.post_params, request.post_params_list, request.post_metadata, and
342 and request.post_metadata_list and/or to call POST field stream handlers that
343 have been previously registered with request:stream_post_param(...) or
344 request:stream_post_params(...).
346 This method gets invoked automatically when the POST param tables
347 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
348 deadlocks with the webbrowser). (Note: Automatic request body processing on
349 write may be disabled by calling request:defer_reading().)
351 After this method returned, all registered POST field stream handlers have
352 received all data. Registration of other POST field stream handlers is not
353 possible after this method has been called (or after request.post_params_list
354 or request.post_params have been accessed).
357 ### request:send_data(...)
359 Sends data as response body. All arguments are converted via tostring(...) and
360 concatenated. May be called multiple times until the request has been finished
361 by calling request:finish().
363 If the request method (see request.method) is "HEAD", then calls to
364 request:send_data(...) are automatically ignored.
367 ### request:send_header(key, value)
369 Sends a HTTP response header that consists of the given key and the given
370 value. Note: Key and value must be provided as separate arguments. Before any
371 headers can be sent, a HTTP status must have been set with
372 request:send_status(status_string).
375 ### request:send_status(status_string)
377 Sends a HTTP response status that is given as a string consisting of a 3-digit
378 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
379 function must be called once before any headers or response body data may be
380 sent.
383 ### request.socket
385 The underlaying socket. Can be used to force a TCP RST, etc.
388 ### request:stream_post_param(field_name, callback)
390 Registers a stream handler for the given POST parameter. The callback function
391 will be called in the following manner:
393 - For the initial chunk, the first chunk gets passed as first argument while a
394 table with metadata ("field_name" and "content_type") gets passed as second
395 argument. In case of an immediate EOF (i.e. an empty file), the passed
396 chunk is the empty string. In all other cases the chunk has a length greater
397 than zero.
398 - For any remaining chunks, the respective chunk gets passed as first and only
399 argument (no metadata). Here, the chunk has always a length greater than
400 zero.
401 - To indicate the end of the stream, the callback function is called without
402 arguments. This also happens in case of an immediate EOF (see above).
404 In case of an immediate EOF (i.e. an empty file), the callback function is thus
405 called as follows:
407 - The first time with an empty string as first argument, and with the metadata
408 as second argument.
409 - The second time without any arguments.
412 ### request:stream_post_params(pattern, callback)
414 Same as request:stream_post_param(...) but providing a string pattern to match
415 multiple field names (e.g. "^file_[0-9]+$").
418 ### request:stream_request_body(callback)
420 Start streaming of request body. For each chunk of the request body, the
421 callback function is called with the corresponding chunk. End of data is
422 indicated through return of request:stream_request_body(...) (not by calling
423 the callback without arguments).
425 The function may be called with nil instead of a callback function. In this
426 case, the request body is read and discarded. Only if nil is passed instead of
427 a callback, then the function may also be invoked when the request body has
428 already been read and/or processed. In the latter case, the function performs
429 no operation.

Impressum / About Us