moonbridge

view reference.txt @ 67:c488f2ea29aa

Fixed typo in moonbridge.c
author jbe
date Sat Apr 04 11:42:34 2015 +0200 (2015-04-04)
parents 3d1f23f1dbc6
children 4628be0a7b98
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 Global function timeout(...)
25 ----------------------------
27 Calling this function with a positive number (time in seconds) sets a timer
28 that kills the current process after the selected time runs out. The remaining
29 time can be queried by calling this function without arguments.
31 Calling this function with a single argument that is the number zero will
32 disable the timeout.
34 Another mode of operation is selected by passing two arguments: a time (in
35 seconds) as first argument and a function as second argument. In this case, a
36 sub-timer will be used to limit the execution time of the function. In case of
37 timeout, the process will be killed (and the timeout function does not return).
38 If the time for the sub-timer is longer than a previously set timeout (using
39 the timeout(...) function with one argument), the shorter timeout (of the
40 previous call of timeout(...)) will have precedence.
42 Timers are also automatically reset (disabled) when a handler (prepare handler
43 or connect handler) returns. To shutdown processes after a certain time waiting
44 for a new request, use the idle_time parameter of the listen function.
48 Function io.poll(read_fds, write_fds, timeout)
49 ----------------------------------------------
51 This function allows to wait for file descriptors to become ready for reading
52 or writing. It accepts the following arguments:
54 1. Table of file descriptors to wait for reading (optional, may be nil)
55 2. Table of file descriptors to wait for writing (optional, may be nil)
56 3. Timeout in seconds (optional, may be nil or zero to disable timeout)
58 Alternatively to file descriptors, the tables may contain file handles (in
59 which case the file descriptor is automatically extracted).
61 Please note that support for non-blocking I/O operations is limited if you use
62 ordinary file handles (as Moonbridge does). It is possible, however, to wait
63 until the first byte to read is available at a file handle. For more
64 information, see socket.input:pending().
68 Socket object passed to "connect" handler
69 -----------------------------------------
71 For every incoming connection, the registered "connect" handler is called with
72 a single socket object as argument, which is described below:
75 ### socket:cancel()
77 Closes the socket connection by sending a TCP RST package if possible to
78 indicate error condition. Returns true on success, or nil plus error message in
79 case of an I/O error. Using this method on sockets that have already been
80 closed (or canceled) will throw an error.
82 Warning: Previously sent (and flushed) data may be lost during transmission.
85 ### socket:close(timeout)
87 Closes the socket connection (input and output stream) by flushing all data and
88 sending a TCP FIN package. Returns true on success, or nil plus error message
89 in case of an I/O error. Using this method on sockets that have already been
90 closed (or canceled) will throw an error.
92 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
93 depending on the particular operating system used. All pending input data
94 should have been read before calling socket:close().
96 The optional timeout parameter may be used to wait until all data has been sent
97 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
98 happens first. A timeout value of 0 or nil causes immediate return and sending
99 of pending data in background (recommended).
102 ### socket:flush()
104 Alias for socket.output:flush()
107 ### socket.input
109 Lua file handle representing the input stream of the socket connection.
110 Supports the same methods as io.open()'s return values.
113 ### socket.input:pending()
115 Returns true if there is at least one byte to read. In case of I/O errors, true
116 is returned as well (to avoid lockup and cause error on subsequent read).
118 Note: Subsequent calls of socket.input:read(...) or socket.input:readuntil(...)
119 may still block when attempting to read more than one byte. To avoid hanging
120 processes, the timeout(...) function may be used as a watchdog that will
121 terminate the process in case of unexpected delay. Because file handles are
122 buffered, data may be still pending even if the underlaying file descriptor
123 does not have any more data to read. Thus, all file handles passed to
124 io.poll(...) to wait for reading should be tested for pending data first.
126 This method is also available as :pending() for any other Lua file handle.
129 ### socket.input:readuntil(terminator, maxlen)
131 Reads as many bytes until a byte equal to the terminator value occurs. An
132 optional maximum length may be specified. The terminating byte is included in
133 the return value (unless the maximum length would be exceeded). On EOF, nil is
134 returned. In case of an I/O error, nil (as first result value) plus an error
135 message (as second result value) is returned.
137 Note: This function may provide a significant speedup compared to byte-wise
138 reading using socket.input:read(1) in a loop. However, this function will block
139 when no data is available. The timeout(...) function may be used as a watchdog
140 that will terminate the process in case of unexpected delay.
142 This method is also available as :readuntil(...) for any other Lua file handle.
145 ### socket.interval
147 Set to the name of an interval timer if the "connect" handler was called due to
148 an elapsed interval timer. Otherwise nil.
151 ### socket:lines()
153 Alias for socket.input:lines()
156 ### socket.local_ip4
158 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
159 string.
162 ### socket.local_ip6
164 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
165 a string.
168 ### socket.local_tcpport
170 Local TCP port used for the connection.
173 ### socket.output
175 Lua file handle representing the output stream of the socket connection.
176 Supports the same methods as io.open()'s return values.
179 ### socket.output:close()
181 Performs a half-close (i.e. sends a TCP FIN package in case of a TCP socket).
183 Note: In order to shut down a TCP connection properly, it may be necessary to
184 read any pending data from socket.input before closing the socket completely
185 (e.g. with socket:close() or by returning from the connect handler). If there
186 is still incoming data, a TCP RST packet might be sent which can cause loss of
187 transmitted data.
190 ### socket:read(...)
192 Alias for socket.input:read()
195 ### socket:readuntil(terminator, maxlen)
197 Alias for socket.input:readuntil(terminator, maxlen)
200 ### socket.remote_ip4
202 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
203 a string.
206 ### socket.remote_ip6
208 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
209 a string.
212 ### socket.remote_tcpport
214 Remote TCP port used for the connection.
217 ### socket:write(...)
219 Alias for socket.output:write(...)
223 HTTP module
224 -----------
226 The http module exports the function http.generate_handler(callback) that
227 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
228 example of invocation. A table with options may be passed either as a second
229 argument, or as a first argument preceeding the callback function (whichever is
230 more convenient).
232 The following options are supported:
234 - request_body_size_limit: maximum size of payload of HTTP request body
235 (transfer encoding is allowed to add a limited amount of extra data)
236 - chunk_size: optional default value for maximum_input_chunk_size and
237 minimum_output_chunk_size
238 - request_header_size_limit: maximum size of HTTP request headers
239 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
240 certain POST fields (bigger chunks will be fragmented automatically)
241 - minimum_output_chunk_size: minimum size for a chunk when sending a response
242 body (smaller chunks will be buffered and concatenated with future data;
243 ignored when request:flush() is called)
244 - static_headers: a set of headers to be included in every HTTP response
245 (may be a string, a table or strings, or a table of key-value pairs)
247 The callback function receives a single request object as argument, which is
248 described below.
251 ### request.body
253 The request body (without headers) as a string. Accessing this value makes
254 further access to request.post_params and request.post_params_list, or
255 invocation of request:stream_request_body(...) impossible.
258 ### request:close_after_finish()
260 Closes the connection after answering the request.
262 This method can only be called before the HTTP response header section has been
263 finished (i.e. before request:finish_headers(), request:send_data(...), or
264 request:finish() were called), but it may be called before a status code has
265 been sent using request:send_status(...).
267 A corresponding "Connection: close" header is automatically sent.
270 ### request.cookies
272 A table with all cookies sent by the client.
275 ### request.defer_reading()
277 Disables automatic request body processing on write. Can be called before
278 sending a HTTP status code to send a response before the request has been fully
279 received.
281 CAUTION: Responding to a request before the request body has been processed may
282 lead to a deadlock if the browser does not process the response while trying to
283 send the request. Therefore, this function should only be used if:
285 - the TCP stack has enough buffer space for the response (i.e. if the response
286 is small enough), and if
287 - a timer is used to cancel the response in case of a deadlock.
289 It is recommended to not use this function unless certain performance tweaks
290 are desired.
293 ### request.faulty
295 Normally set to false. In case of a read or write error on the client
296 connection, this value is set to true before a Lua error is raised.
298 A faulty request handle must not be used, or another Lua error will be raised.
301 ### request:finish()
303 Finishes and flushes a HTTP response. May be called multiple times. An
304 HTTP status, all headers, and the response body (if applicable) must have been
305 previously sent. After calling this method, no further data may be written.
308 ### request:finish_headers()
310 Finishes and flushes the HTTP response header section. May be called multiple
311 times, as long as the request is not finished completely. This method is
312 automatically invoked if the application is beginning to send a response body.
313 After calling this method, no further headers may be sent.
316 ### request:flush()
318 Flushes any pending output data. Note: In order to mark the end of a response
319 body, it is required to call request:finish().
322 ### request.get_params
324 A table that maps field names to their corresponding GET value. If there are
325 several GET values with the given field name, then the first value is used.
327 Note: May be implemented through metamethods, but does support iteration
328 through pairs(...).
331 ### request.get_params_list
333 A table that maps field names to a sequence of their corresponding GET values.
335 Note: May be implemented through metamethods, but does support iteration
336 through pairs(...).
339 ### request.headers
341 A table that maps (case-insensitively) a HTTP header field name to a sequence
342 of values. One entry is created for every occurrence of a header line with the
343 given field name).
346 ### request.headers_csv_string
348 A table that maps (case-insensitively) a HTTP header field name to a comma
349 separated string. Multiple occurrences of the header with the given field name
350 are automatically merged into the comma separated string.
353 ### request.headers_csv_table
355 A table that maps (case-insensitively) a HTTP header field name to a sequence
356 of values. One entry is created for every comma separated value of each header
357 with the given field name.
360 ### request.headers_flags
362 A table that maps (case-insensitively) a HTTP header field name to another
363 table which (again case-insensitively) maps a string to a boolean, depending on
364 whether this string occurred in the list of comma separated values of one
365 header line with the given field name that was the key in the first table.
368 ### request.headers_value
370 A table that maps (case-insensitively) a HTTP header field name to a value. If
371 multiple header lines with the given field name have been received, false is
372 used as value.
375 ### request.method
377 The HTTP request method, e.g. "HEAD", "GET", or "POST".
380 ### request.path
382 The requested path without a leading slash and without the query part (e.g.
383 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
384 see request.query.
386 This value will be nil if (and only if) the request method is "OPTIONS" with a
387 request target equal to "*" (see also asterisk-form of request-target in
388 section 5.3.4 in RFC 7230).
391 ### request.post_metadata
393 Only set for multipart/form-data POST requests. A table that maps field names
394 to their corresponding POST metadata table which contains two entries:
395 "file_name" and "content_type". If there are several POST values with the given
396 field name, then the first value/file is used.
399 ### request.post_metadata_list
401 Only set for multipart/form-data POST requests. A table that maps field names
402 to a sequence with their corresponding POST metadata tables. Needed if multiple
403 files are uploaded with the same field name.
406 ### request.post_params
408 A table that maps field names to their corresponding POST value. If there are
409 several POST values with the given field name, then the first value is used.
411 Note: May be implemented through metamethods, but does support iteration
412 through pairs(...).
415 ### request.post_params_list
417 A table that maps field names to a sequence of their corresponding POST values.
419 Note: May be implemented through metamethods, but does support iteration
420 through pairs(...).
423 ### request.query
425 Query part of the request target including the leading question mark, e.g.
426 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
427 automatically parsed and made available through request.get_params and
428 request.get_params_list.
430 If there is no query part given in the request target, then this string is
431 the empty string. This value will be nil if (and only if) the request method
432 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
433 request-target in section 5.3.4 in RFC 7230).
436 ### request:process_request_body()
438 Starts processing the request body (if existent) to set the values
439 request.post_params, request.post_params_list, request.post_metadata, and
440 and request.post_metadata_list and/or to call POST field stream handlers that
441 have been previously registered with request:stream_post_param(...) or
442 request:stream_post_params(...).
444 This method gets invoked automatically when the POST param tables
445 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
446 deadlocks with the webbrowser). (Note: Automatic request body processing on
447 write may be disabled by calling request:defer_reading().)
449 After this method returned, all registered POST field stream handlers have
450 received all data. Registration of other POST field stream handlers is not
451 possible after this method has been called (or after request.post_params_list
452 or request.post_params have been accessed).
455 ### request:send_data(...)
457 Sends data as response body. All arguments are converted via tostring(...) and
458 concatenated. May be called multiple times until the request has been finished
459 by calling request:finish().
461 If the request method (see request.method) is "HEAD", then calls to
462 request:send_data(...) are automatically ignored.
465 ### request:send_header(key, value)
467 Sends a HTTP response header that consists of the given key and the given
468 value. Note: Key and value must be provided as separate arguments. Before any
469 headers can be sent, a HTTP status must have been set with
470 request:send_status(status_string).
473 ### request:send_status(status_string)
475 Sends a HTTP response status that is given as a string consisting of a 3-digit
476 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
477 function must be called once before any headers or response body data may be
478 sent.
481 ### request.socket
483 The underlaying socket. Can be used to force a TCP RST, etc.
486 ### request:stream_post_param(field_name, callback)
488 Registers a stream handler for the given POST parameter. The callback function
489 will be called in the following manner:
491 - For the initial chunk, the first chunk gets passed as first argument while a
492 table with metadata ("field_name" and "content_type") gets passed as second
493 argument. In case of an immediate EOF (i.e. an empty file), the passed
494 chunk is the empty string. In all other cases the chunk has a length greater
495 than zero.
496 - For any remaining chunks, the respective chunk gets passed as first and only
497 argument (no metadata). Here, the chunk has always a length greater than
498 zero.
499 - To indicate the end of the stream, the callback function is called without
500 arguments. This also happens in case of an immediate EOF (see above).
502 In case of an immediate EOF (i.e. an empty file), the callback function is thus
503 called as follows:
505 - The first time with an empty string as first argument, and with the metadata
506 as second argument.
507 - The second time without any arguments.
510 ### request:stream_post_params(pattern, callback)
512 Same as request:stream_post_param(...) but providing a string pattern to match
513 multiple field names (e.g. "^file_[0-9]+$").
516 ### request:stream_request_body(callback)
518 Start streaming of request body. For each chunk of the request body, the
519 callback function is called with the corresponding chunk. End of data is
520 indicated through return of request:stream_request_body(...) (not by calling
521 the callback without arguments).
523 The function may be called with nil instead of a callback function. In this
524 case, the request body is read and discarded. Only if nil is passed instead of
525 a callback, then the function may also be invoked when the request body has
526 already been read and/or processed. In the latter case, the function performs
527 no operation.

Impressum / About Us