moonbridge

view reference.txt @ 217:0b6555732047

Changed version number to 1.0.0
author jbe
date Tue Jun 23 02:05:46 2015 +0200 (2015-06-23)
parents 5601a486e68a
children 35ea31e45b43
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 Socket object passed to "connect" handler
49 -----------------------------------------
51 For every incoming connection, the registered "connect" handler is called with
52 a single socket object as argument, which is described below:
55 ### socket:close()
57 Closes the socket connection (input and output stream) by flushing all data and
58 sending a TCP FIN packet.
60 Returns true on success, or nil plus error message in case of an I/O error.
61 Using this method on sockets that have already been closed (or reset) will
62 throw an error.
64 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
65 when network connections are used. All pending input data should have been read
66 (or drained) before calling socket:close(). Use socket:finish() to send a
67 TCP FIN packet to the peer before waiting for EOF from the peer.
70 ### socket:drain(maxlen, terminator)
72 Same as socket:read(maxlen, terminator), but discards the input and returns the
73 number of discarded bytes (as first return value) and the status code ("term",
74 "maxlen", "eof" as second return value).
76 In case of an I/O error, nil (as first return value) plus an error message (as
77 second return value) are returned.
80 ### socket:drain_call(waitfunc, maxlen, terminator)
82 Same as socket:drain(maxlen, terminator), but calls waitfunc(socket, "r") (in
83 an infinite loop) as long as the reading is blocked.
86 ### socket:drain_nb(maxlen, terminator)
88 Same as socket:drain(maxlen, terminator), but non-blocking. The status code
89 (which is returned as second return value) may therefore be "term", "maxlen",
90 "eof", or "block".
92 In case of an I/O error, nil (as first return value) plus an error message (as
93 second return value) are returned.
96 ### socket:drain_yield(maxlen, terminator)
98 Alias for socket:drain_call(coroutine.yield, maxlen, terminator)
101 ### socket:finish()
103 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
104 still possible. When there is no more input data to be read, the connection
105 should finally be closed with socket:close().
107 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
108 the underlying socket and emulates EOF on subsequent reads. Also in this case,
109 the connection should be finally closed with socket:close().
112 ### socket:flush(...)
114 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
115 data is passed to the operating system).
117 In case of an I/O error, nil (as first return value) plus an error message (as
118 second return value) are returned. On success, the socket userdata object is
119 returned.
122 ### socket:flush_call(waitfunc, ...)
124 Same as socket:flush(...), but calls waitfunc() (in an infinite loop) as long
125 as the writing is blocked.
128 ### socket:flush_nb(...)
130 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
131 pending data is passed to the operating system). The total number of bytes that
132 could not be passed yet to the operating system is returned. Zero is returned
133 if all data could be flushed out.
135 In case of an I/O error, nil (as first return value) plus an error message (as
136 second return value) are returned.
139 ### socket:flush_yield(...)
141 Alias for socket:flush_call(coroutine.yield, ...)
144 ### socket.interval
146 Set to the name of an interval timer if the "connect" handler was called due to
147 an elapsed interval timer. Otherwise nil.
150 ### socket.local_ip4
152 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
153 string.
156 ### socket.local_ip6
158 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
159 a string.
162 ### socket.local_tcpport
164 Local TCP port used for the connection.
167 ### socket:read(maxlen, terminator)
169 Reads up to maxlen bytes or until an optional termination character is
170 encountered (which is included in the result). The maxlen value may be nil, in
171 which case there is no limit on the number of bytes read.
173 In case of an I/O error, nil (as first return value) plus an error message (as
174 second return value) are returned.
176 In all other cases (including EOF), the following two values are returned:
178 - a string containing the bytes read (first return value, may be empty string)
179 - a status code equal to "term", "maxlen", or "eof" (second return value)
181 If an EOF is encountered before all data could be read, then "eof" is returned
182 as second return value. If maxlen bytes have been read and no termination
183 character has been read, then "maxlen" is returned as second return value. If
184 the termination character is the last character of the read string, the second
185 return value will be "term".
188 ### socket:read_call(waitfunc, maxlen, terminator)
190 Same as socket:read(maxlen, terminator), but calls waitfunc() (in an infinite
191 loop) as long as the reading is blocked.
194 ### socket:read_nb(maxlen, terminator)
196 Same as socket:read(maxlen, terminator), but does not block.
198 In case of an I/O error, nil (as first return value) plus an error message (as
199 second return value) are returned.
201 In all other cases (including EOF), the following two values are returned:
203 - a string containing the bytes read (first return value, may be empty string)
204 - a status code equal to "term", "maxlen", "eof", "block" (second return value)
206 The status code "block" as second return value is used if the function returned
207 prematurely because it would block otherwise. In this case, the first return
208 value is a string that contains the bytes that could be read without blocking.
211 ### socket:read_yield(maxlen, terminator)
213 Alias for socket:read_call(coroutine.yield, maxlen, terminator)
216 ### socket.remote_ip4
218 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
219 a string.
222 ### socket.remote_ip6
224 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
225 a string.
228 ### socket.remote_tcpport
230 Remote TCP port used for the connection.
233 ### socket:reset()
235 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
236 packet if possible to indicate error condition.
238 Returns true on success, or nil (as first return value) plus error message (as
239 second return value) in case of an I/O error. Using this method on sockets that
240 have already been closed (or reset) will throw an error.
242 Warning: Previously sent (and flushed) data may be lost during transmission.
245 ### socket:write(...)
247 Takes a variable number of strings and sends them to the peer. The operation is
248 buffered, so to actually send out the data, it is necessary to eventually call
249 socket:flush(), socket:finish(), or socket:close().
251 In case of an I/O error, nil (as first return value) plus an error message (as
252 second return value) are returned. On success, the socket userdata object is
253 returned.
256 ### socket:write_call(waitfunc, ...)
258 Same as socket:write(...), but calls waitfunc() (in an infinite loop) as long
259 as the writing is blocked.
262 ### socket:write_nb(...)
264 Takes a variable number of strings and sends them to the peer. The operation is
265 buffered, so to actually send out the data, it is necessary to eventually call
266 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
268 This function always returns immediately (i.e. it does not block). If all data
269 (but a small buffered portion) could be sent out, then zero is returned.
270 Otherwise, all arguments that could not be sent are stored in a buffer of
271 unlimited size (up to memory capabilities) and an integer is returned that
272 indicates the number of bytes currently in the buffer.
274 In case of an I/O error, nil (as first return value) plus an error message (as
275 second return value) are returned.
278 ### socket:write_yield(...)
280 Alias for socket:write_call(coroutine.yield, ...)
284 I/O library
285 -----------
287 The Moonbridge Network Server for Lua Applications comes with its own I/O
288 library to support blocking as well as nonblocking I/O operations.
290 All methods on an I/O handle (e.g. socket) are described in the previous
291 section regarding the "socket" object. All other functions of the library are
292 listed below.
295 ### moonbridge_io.exec(command, arg1, arg2, ...)
297 Executes the given command and returns a handle with three sockets named
298 "stdin", "stdout", and "stderr" as well as the following methods:
300 - :kill(signal)
301 - :wait()
302 - :wait_nb()
303 - :wait_call(waitfunc)
304 - :wait_yield()
306 Use :kill(signal) to terminate the process with the given signal (defaults to
307 SIGTERM).
309 The :wait() method will wait for the process to terminate and return its exit
310 code. If the process was terminated by a signal, a negative integer is returned
311 which corresponds to the respective positive signal number.
313 The method :wait_nb() is the same as :wait(), except that it does not block but
314 returns nil if the child process has not terminated yet.
316 The method :wait_call() is the same as :wait() but calls waitfunc() (in an
317 infinite loop) as long as the process is still running.
319 The method :wait_yield() is an alias for :wait_call(coroutine.yield).
322 ### moonbridge_io.localconnect(path)
324 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
325 a socket object on success, or nil (as first return value) plus an error
326 message (as second return value) in case of error.
329 ### moonbridge_io.localconnect_nb(path)
331 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
332 a socket object on success, or nil (as first return value) plus an error
333 message (as second return value) in case of error.
335 Same as moonbridge_io.localconnect(path), except that this function does not
336 block and immediately returns a socket object.
338 In case of an I/O error, nil (as first return value) plus an error message (as
339 second return value) may be returned. However, connection errors may also be
340 reported on first read or write on the socket.
343 ### moonbridge_io.locallisten(path)
345 Attempts to create a local socket (also known as Unix Domain Socket) to accept
346 incoming connections. If the file does already exist and is a socket, then it
347 is deleted automatically before being re-created.
349 In case of an I/O error, nil (as first return value) plus an error message (as
350 second return value) may be returned.On success, a listener object is returned
351 which supports the methods :accept(), :accept_nb(), and :close().
353 The method :accept() blocks until a new incoming connection is available in
354 which case a socket object is returned.
356 The method :accept_nb() works like :accept(), except that the call is
357 nonblocking and returns false (plus a notice as second return value) in case no
358 incoming connection is available. It is possible to wait for an incoming
359 connection by including the listener object in the input_set of the
360 moonbridge_io.poll(...) call.
362 The method :close() will close the listening socket. In case of local sockets
363 (Unix Domain Sockets), the socket will not be unlinked in the file system.
365 I/O errors by the methods of the listener object are also reported by returning
366 nil (as first return value) plus an error message (as second return value).
369 ### moonbridge_io.poll(input_set, output_set, timeout)
371 This function waits for at least one of the given file descriptors and/or
372 I/O handles to be ready for input or output. The two sets of file descriptors
373 and/or handles must contain the file descriptor or handle as a key, and a value
374 which does evaluate to true. If a set is nil, it is treated as being empty.
376 Returns true when at least one file descriptor or handle is ready for reading
377 or writing respectively. Returns false (as first return value) plus a status
378 message (as second return value) in case of timeout or when a signal was
379 received.
382 ### moonbridge_io.tcpconnect(hostname, port)
384 Tries to open a TCP connection with the given host and TCP port number. Returns
385 a socket object on success, or nil (as first return value) plus an error
386 message (as second return value) in case of error.
389 ### moonbridge_io.tcpconnect_nb(hostname, port)
391 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
392 does not block and immediately returns a socket object.
394 Note: The current implementation still blocks during the DNS lookup. Use a
395 numeric IP address as hostname to be truly nonblocking.
397 In case of an I/O error, nil (as first return value) plus an error message (as
398 second return value) may be returned. However, connection errors may also be
399 reported on first read or write on the socket.
402 ### moonbridge_io.tcplisten(hostname, port)
404 Attempts to open a TCP port for listening. To listen on the loopback interface,
405 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
406 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
407 "0.0.0.0" (IPv4) respectively.
409 In case of an I/O error, nil (as first return value) plus an error message (as
410 second return value) may be returned. On success, a listener object is returned
411 which supports the methods :accept(), :accept_nb(), and :close(). See reference
412 for moonbridge.io_locallisten(...).
416 HTTP module
417 -----------
419 The http module exports the function http.generate_handler(callback) that
420 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
421 example of invocation. A table with options may be passed either as a second
422 argument, or as a first argument preceeding the callback function (whichever is
423 more convenient).
425 The following options are supported:
427 - request_body_size_limit: maximum size of payload of HTTP request body
428 (transfer encoding is allowed to add a limited amount of extra data)
429 - chunk_size: optional default value for maximum_input_chunk_size and
430 minimum_output_chunk_size
431 - request_header_size_limit: maximum size of HTTP request headers
432 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
433 certain POST fields (bigger chunks will be fragmented automatically)
434 - minimum_output_chunk_size: minimum size for a chunk when sending a response
435 body (smaller chunks will be buffered and concatenated with future data;
436 ignored when request:flush() is called)
437 - static_headers: a set of headers to be included in every HTTP response
438 (may be a string, a table or strings, or a table of key-value pairs)
440 The callback function receives a single request object as argument, which is
441 described below.
444 ### request.body
446 The request body (without headers) as a string. Accessing this value makes
447 further access to request.post_params and request.post_params_list, or
448 invocation of request:stream_request_body(...) impossible.
451 ### request:close_after_finish()
453 Closes the connection after answering the request.
455 This method can only be called before the HTTP response header section has been
456 finished (i.e. before request:finish_headers(), request:send_data(...), or
457 request:finish() were called), but it may be called before a status code has
458 been sent using request:send_status(...).
460 A corresponding "Connection: close" header is automatically sent.
462 See also request:monologue().
465 ### request:consume_input()
467 Starts processing the request body (if existent) to set the values
468 request.post_params, request.post_params_list, request.post_metadata, and
469 and request.post_metadata_list and/or to call POST field stream handlers that
470 have been previously registered with request:stream_post_param(...) or
471 request:stream_post_params(...), or to call a previously registered request
472 body stream handler that was set with request:set_request_body_streamer().
474 This method gets invoked automatically when the POST param tables
475 (request.post_params, etc.) are accessed or if request.body is accessed.
478 ### request.cookies
480 A table with all cookies sent by the client.
483 ### request.faulty
485 Normally set to false. In case of a write error on the client connection or
486 certain other unexpected errors, this value is set to true before a Lua error
487 is raised.
489 A faulty request handle must not be used, or another Lua error will be raised.
492 ### request:finish()
494 Finishes and flushes a HTTP response. May be called multiple times. An
495 HTTP status, all headers, and the response body (if applicable) must have been
496 previously sent. After calling this method, no further data may be written.
499 ### request:finish_headers()
501 Finishes and flushes the HTTP response header section. May be called multiple
502 times, as long as the request is not finished completely. This method is
503 automatically invoked if the application is beginning to send a response body.
504 After calling this method, no further headers may be sent.
507 ### request:flush()
509 Flushes any pending output data. Note: In order to mark the end of a response
510 body, it is required to call request:finish().
513 ### request.fresh
515 Set to false whenever the request object has been used (e.g. data has been read
516 or sent out, or a stream handler was installed); true otherwise.
519 ### request.get_params
521 A table that maps field names to their corresponding GET value. If there are
522 several GET values with the given field name, then the first value is used.
524 Note: May be implemented through metamethods, but does support iteration
525 through pairs(...).
528 ### request.get_params_list
530 A table that maps field names to a sequence of their corresponding GET values.
532 Note: May be implemented through metamethods, but does support iteration
533 through pairs(...).
536 ### request.headers
538 A table that maps (case-insensitively) a HTTP header field name to a sequence
539 of values. One entry is created for every occurrence of a header line with the
540 given field name).
543 ### request.headers_csv_string
545 A table that maps (case-insensitively) a HTTP header field name to a comma
546 separated string. Multiple occurrences of the header with the given field name
547 are automatically merged into the comma separated string.
550 ### request.headers_csv_table
552 A table that maps (case-insensitively) a HTTP header field name to a sequence
553 of values. One entry is created for every comma separated value of each header
554 with the given field name.
557 ### request.headers_flags
559 A table that maps (case-insensitively) a HTTP header field name to another
560 table which (again case-insensitively) maps a string to a boolean, depending on
561 whether this string occurred in the list of comma separated values of one
562 header line with the given field name that was the key in the first table.
565 ### request.headers_value
567 A table that maps (case-insensitively) a HTTP header field name to a value. If
568 multiple header lines with the given field name have been received, false is
569 used as value.
572 ### request.method
574 The HTTP request method, e.g. "HEAD", "GET", or "POST".
577 ### request:monologue()
579 Same as request:close_after_finish() but additionally discards all input data
580 immediately.
583 ### request.path
585 The requested path without a leading slash and without the query part (e.g.
586 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
587 see request.query.
589 This value will be nil if (and only if) the request method is "OPTIONS" with a
590 request target equal to "*" (see also asterisk-form of request-target in
591 section 5.3.4 in RFC 7230).
594 ### request.post_metadata
596 Only set for multipart/form-data POST requests. A table that maps field names
597 to their corresponding POST metadata table which contains two entries:
598 "file_name" and "content_type". If there are several POST values with the given
599 field name, then the first value/file is used.
602 ### request.post_metadata_list
604 Only set for multipart/form-data POST requests. A table that maps field names
605 to a sequence with their corresponding POST metadata tables. Needed if multiple
606 files are uploaded with the same field name.
609 ### request.post_params
611 A table that maps field names to their corresponding POST value. If there are
612 several POST values with the given field name, then the first value is used.
614 Note: May be implemented through metamethods, but does support iteration
615 through pairs(...).
618 ### request.post_params_list
620 A table that maps field names to a sequence of their corresponding POST values.
622 Note: May be implemented through metamethods, but does support iteration
623 through pairs(...).
626 ### request.query
628 Query part of the request target including the leading question mark, e.g.
629 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
630 automatically parsed and made available through request.get_params and
631 request.get_params_list.
633 If there is no query part given in the request target, then this string is
634 the empty string. This value will be nil if (and only if) the request method
635 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
636 request-target in section 5.3.4 in RFC 7230).
639 ### request:send_data(...)
641 Sends data as response body. All arguments are converted via tostring(...) and
642 concatenated. May be called multiple times until the request has been finished
643 by calling request:finish().
645 If the request method (see request.method) is "HEAD", then calls to
646 request:send_data(...) are automatically ignored.
649 ### request:send_header(key, value)
651 Sends a HTTP response header that consists of the given key and the given
652 value. Note: Key and value must be provided as separate arguments. Before any
653 headers can be sent, a HTTP status must have been set with
654 request:send_status(status_string).
657 ### request:send_status(status_string)
659 Sends a HTTP response status that is given as a string consisting of a 3-digit
660 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
661 function must be called once before any headers or response body data may be
662 sent.
665 ### request.socket
667 The underlaying socket. Can be used to force a TCP RST, etc.
670 ### request:stream_post_param(field_name, callback)
672 Registers a stream handler for the given POST parameter. The callback function
673 will be called in the following manner:
675 - For the initial chunk, the first chunk gets passed as first argument while a
676 table with metadata ("field_name" and "content_type") gets passed as second
677 argument. In case of an immediate EOF (i.e. an empty file), the passed
678 chunk is the empty string. In all other cases the chunk has a length greater
679 than zero.
680 - For any remaining chunks, the respective chunk gets passed as first and only
681 argument (no metadata). Here, the chunk has always a length greater than
682 zero.
683 - To indicate the end of the stream, the callback function is called without
684 arguments. This also happens in case of an immediate EOF (see above).
686 In case of an immediate EOF (i.e. an empty file), the callback function is thus
687 called as follows:
689 - The first time with an empty string as first argument, and with the metadata
690 as second argument.
691 - The second time without any arguments.
693 Note that request:consume_input() needs to be called to enforce streaming to
694 finish.
697 ### request:stream_post_params(pattern, callback)
699 Same as request:stream_post_param(...) but providing a string pattern to match
700 multiple field names (e.g. "^file_[0-9]+$").
703 ### request:stream_request_body(callback)
705 Registeres a stream handler for the whole request body. For each chunk of the
706 request body, the callback function is called with the corresponding chunk. End
707 of data is indicated by passing a nil value to the callback functuion.
709 Note that request:consume_input() needs to be called to enforce streaming to
710 finish.
713 ### request:stream_request_body_now(callback)
715 Start streaming of request body immediately. On EOF the function returns and
716 the callback function is *not* called with nil as argument.
718 Note that request:consume_input() needs to be called to enforce streaming to
719 finish.

Impressum / About Us