moonbridge
view reference.txt @ 284:28aab22e68b6
New implementation of SIGTERM handling
| author | jbe |
|---|---|
| date | Sun Jun 11 00:02:43 2017 +0200 (2017-06-11) |
| parents | 6bb191b6ead5 |
| children | a7395fb91ec3 |
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.
69 A socket passed to the "connect" handler will be closed automatically if it was
70 not closed by the "connect" handler and if the "connect" handler returns
71 normally (i.e. without throwing an error). If the "connect" handler throws an
72 error, then the socket will be reset. See socket:reset().
75 ### socket:drain(maxlen, terminator)
77 Same as socket:read(maxlen, terminator), but discards the input and returns the
78 number of discarded bytes (as first return value) and the status code ("term",
79 "maxlen", "eof" as second return value).
81 In case of an I/O error, nil (as first return value) plus an error message (as
82 second return value) are returned.
85 ### socket:drain_call(waitfunc, maxlen, terminator)
87 Same as socket:drain(maxlen, terminator), but calls waitfunc() (in an infinite
88 loop) as long as the reading is blocked.
91 ### socket:drain_nb(maxlen, terminator)
93 Same as socket:drain(maxlen, terminator), but non-blocking. The status code
94 (which is returned as second return value) may therefore be "term", "maxlen",
95 "eof", or "block".
97 In case of an I/O error, nil (as first return value) plus an error message (as
98 second return value) are returned.
101 ### socket:drain_yield(maxlen, terminator)
103 Alias for socket:drain_call(coroutine.yield, maxlen, terminator)
106 ### socket:finish()
108 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
109 still possible. When there is no more input data to be read, the connection
110 should finally be closed with socket:close().
112 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
113 the underlying socket and emulates EOF on subsequent reads. Also in this case,
114 the connection should be finally closed with socket:close().
117 ### socket:flush(...)
119 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
120 data is passed to the operating system).
122 In case of an I/O error, nil (as first return value) plus an error message (as
123 second return value) are returned. On success, the socket userdata object is
124 returned.
127 ### socket:flush_call(waitfunc, ...)
129 Same as socket:flush(...), but calls waitfunc() (in an infinite loop) as long
130 as the writing is blocked.
133 ### socket:flush_nb(...)
135 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
136 pending data is passed to the operating system). The total number of bytes that
137 could not be passed yet to the operating system is returned. Zero is returned
138 if all data could be flushed out.
140 In case of an I/O error, nil (as first return value) plus an error message (as
141 second return value) are returned.
144 ### socket:flush_yield(...)
146 Alias for socket:flush_call(coroutine.yield, ...)
149 ### socket.interval
151 Set to the name of an interval timer if the "connect" handler was called due to
152 an elapsed interval timer. Otherwise nil.
155 ### socket.local_ip4
157 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
158 string.
161 ### socket.local_ip6
163 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
164 a string.
167 ### socket.local_tcpport
169 Local TCP port used for the connection.
172 ### socket:read(maxlen, terminator)
174 Reads up to maxlen bytes or until an optional termination character is
175 encountered (which is included in the result). The maxlen value may be nil, in
176 which case there is no limit on the number of bytes read.
178 In case of an I/O error, nil (as first return value) plus an error message (as
179 second return value) are returned.
181 In all other cases (including EOF), the following two values are returned:
183 - a string containing the bytes read (first return value, may be empty string)
184 - a status code equal to "term", "maxlen", or "eof" (second return value)
186 If an EOF is encountered before all data could be read, then "eof" is returned
187 as second return value. If maxlen bytes have been read and no termination
188 character has been read, then "maxlen" is returned as second return value. If
189 the termination character is the last character of the read string, the second
190 return value will be "term".
193 ### socket:read_call(waitfunc, maxlen, terminator)
195 Same as socket:read(maxlen, terminator), but calls waitfunc() (in an infinite
196 loop) as long as the reading is blocked.
199 ### socket:read_nb(maxlen, terminator)
201 Same as socket:read(maxlen, terminator), but does not block.
203 In case of an I/O error, nil (as first return value) plus an error message (as
204 second return value) are returned.
206 In all other cases (including EOF), the following two values are returned:
208 - a string containing the bytes read (first return value, may be empty string)
209 - a status code equal to "term", "maxlen", "eof", "block" (second return value)
211 The status code "block" as second return value is used if the function returned
212 prematurely because it would block otherwise. In this case, the first return
213 value is a string that contains the bytes that could be read without blocking.
216 ### socket:read_yield(maxlen, terminator)
218 Alias for socket:read_call(coroutine.yield, maxlen, terminator)
221 ### socket.remote_ip4
223 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
224 a string.
227 ### socket.remote_ip6
229 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
230 a string.
233 ### socket.remote_tcpport
235 Remote TCP port used for the connection.
238 ### socket:reset()
240 Alias for socket:close(). Closes the socket connection by sending a TCP RST
241 packet if possible to indicate error condition. This is the default operation
242 when a socket handle gets garbage collected or the process is terminated
243 abnormally.
245 Returns true on success, or nil (as first return value) plus error message (as
246 second return value) in case of an I/O error. Using this method on sockets that
247 have already been closed (or reset) will throw an error.
249 Warning: Previously sent (and flushed) data may be lost during transmission.
252 ### socket:write(...)
254 Takes a variable number of strings and sends them to the peer. The operation is
255 buffered, so to actually send out the data, it is necessary to eventually call
256 socket:flush(), socket:finish(), or socket:close().
258 In case of an I/O error, nil (as first return value) plus an error message (as
259 second return value) are returned. On success, the socket userdata object is
260 returned.
263 ### socket:write_call(waitfunc, ...)
265 Same as socket:write(...), but calls waitfunc() (in an infinite loop) as long
266 as the writing is blocked.
269 ### socket:write_nb(...)
271 Takes a variable number of strings and sends them to the peer. The operation is
272 buffered, so to actually send out the data, it is necessary to eventually call
273 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
275 This function always returns immediately (i.e. it does not block). If all data
276 (but a small buffered portion) could be sent out, then zero is returned.
277 Otherwise, all arguments that could not be sent are stored in a buffer of
278 unlimited size (up to memory capabilities) and an integer is returned that
279 indicates the number of bytes currently in the buffer.
281 In case of an I/O error, nil (as first return value) plus an error message (as
282 second return value) are returned.
285 ### socket:write_yield(...)
287 Alias for socket:write_call(coroutine.yield, ...)
291 I/O library
292 -----------
294 The Moonbridge Network Server for Lua Applications comes with its own I/O
295 library to support blocking as well as nonblocking I/O operations.
297 All methods on an I/O handle (e.g. socket) are described in the previous
298 section regarding the "socket" object. All other functions of the library are
299 listed below.
302 ### moonbridge_io.exec(command, arg1, arg2, ...)
304 Executes the given command and returns a handle with three sockets named
305 "stdin", "stdout", and "stderr" as well as the following methods:
307 - :kill(signal)
308 - :wait()
309 - :wait_nb()
310 - :wait_call(waitfunc)
311 - :wait_yield()
313 Use :kill(signal) to terminate the process with the given signal (defaults to 9
314 for SIGKILL).
316 The :wait() method will wait for the process to terminate and return its exit
317 code. If the process was terminated by a signal, a negative integer is returned
318 which corresponds to the respective positive signal number.
320 The method :wait_nb() is the same as :wait(), except that it does not block but
321 returns false (plus a notice as second return value) if the child process has
322 not terminated yet.
324 The method :wait_call() is the same as :wait() but calls waitfunc() (in an
325 infinite loop) as long as the process is still running.
327 The method :wait_yield() is an alias for :wait_call(coroutine.yield).
329 moonbridge_io.exec(...) returns nil (as first return value) plus an error
330 message (as second return value) in case of error.
333 ### moonbridge_io.localconnect(path)
335 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
336 a socket object on success, or nil (as first return value) plus an error
337 message (as second return value) in case of error.
340 ### moonbridge_io.localconnect_nb(path)
342 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
343 a socket object on success, or nil (as first return value) plus an error
344 message (as second return value) in case of error.
346 Same as moonbridge_io.localconnect(path), except that this function does not
347 block and immediately returns a socket object.
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. However, connection errors may also be
351 reported on first read or write on the socket.
354 ### moonbridge_io.locallisten(path)
356 Attempts to create a local socket (also known as Unix Domain Socket) to accept
357 incoming connections. If the file does already exist and is a socket, then it
358 is deleted automatically before being re-created.
360 In case of an I/O error, nil (as first return value) plus an error message (as
361 second return value) may be returned. On success, a listener object is returned
362 which supports the methods :accept(), :accept_nb(), and :close().
364 The method :accept() blocks until a new incoming connection is available, in
365 which case a socket object is returned.
367 The method :accept_nb() works like :accept(), except that the call is
368 nonblocking and returns false (plus a notice as second return value) in case no
369 incoming connection is available. It is possible to wait for an incoming
370 connection by including the listener object in the input_set of the
371 moonbridge_io.poll(...) call.
373 The method :close() will close the listening socket. In case of local sockets
374 (Unix Domain Sockets), the socket will not be unlinked in the file system.
376 I/O errors by the methods of the listener object are also reported by returning
377 nil (as first return value) plus an error message (as second return value).
380 ### moonbridge_io.poll(input_set, output_set, timeout, wakeup_on_sigterm)
382 This function waits for at least one of the given file descriptors and/or
383 I/O handles to be ready for input or output. The two sets of file descriptors
384 and/or handles must contain the file descriptor or handle as a key, and a value
385 which does evaluate to true, e.g. input_set = {[socketA] = true}. If a set is
386 nil, it is treated as being empty.
388 Returns false (plus a notice as second return value) in case of timeout. If the
389 4th parameter is set to true, also returns false (plus a notice) when a SIGTERM
390 has been received since a corresponding signal handler has been installed with
391 moonbridge_io.sigterm_setup().
393 Returns true when at least one file descriptor or handle is ready for reading
394 or writing respectively. The function may also return true if signals have been
395 received during waiting (unless the 4th parameter is set to true and a SIGTERM
396 was received).
399 ### moonbridge_io.signals
401 A table mapping a string (e.g. "TERM" or "KILL") to the corresponding signal
402 number (e.g. 9 or 15, respectively).
405 ### moonbridge_io.sigterm_received()
407 Returns true if a SIGTERM was received after moonbridge_io.sigterm_setup() has
408 installed a corresponding signal handler. The function will then always return
409 true until the process terminates.
412 ### moonbridge_io.sigterm_setup()
414 This function installs a signal handler for SIGTERM. Use the function
415 moonbridge_io.sigterm_received() to check whether the signal has been received.
416 In addition, moonbridge_io.poll(...) will wakeup prematurely if the
417 4th parameter is set to true.
420 ### moonbridge_io.tcpconnect(hostname, port)
422 Tries to open a TCP connection with the given host and TCP port number. Returns
423 a socket object on success, or nil (as first return value) plus an error
424 message (as second return value) in case of error.
427 ### moonbridge_io.tcpconnect_nb(hostname, port)
429 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
430 does not block and immediately returns a socket object.
432 Note: The current implementation still blocks during the DNS lookup. Use a
433 numeric IP address as hostname to be truly nonblocking.
435 In case of an I/O error, nil (as first return value) plus an error message (as
436 second return value) may be returned. However, connection errors may also be
437 reported on first read or write on the socket.
440 ### moonbridge_io.tcplisten(hostname, port)
442 Attempts to open a TCP port for listening. To listen on the loopback interface,
443 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
444 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
445 "0.0.0.0" (IPv4) respectively.
447 In case of an I/O error, nil (as first return value) plus an error message (as
448 second return value) may be returned. On success, a listener object is returned
449 which supports the methods :accept(), :accept_nb(), and :close(). See reference
450 for moonbridge.io_locallisten(...).
453 ### moonbridge_io.timeref(previous)
455 Helper function which returns a time reference (in SI-seconds). If a value is
456 passed as an optional argument to the function, then that value is substracted
457 from the result. A common idiom is:
459 local starttime = moonbridge_io.timeref()
460 [...]
461 while true do
462 [...]
463 if not moonbridge_io.poll(
464 input_set,
465 output_set,
466 timeout - moonbridge_io.timeref(starttime)
467 ) then
468 error("Timeout")
469 end
470 [...]
471 end
475 HTTP module
476 -----------
478 The HTTP module exports the function moonbridge_http.generate_handler(callback)
479 that converts an HTTP handler to a "connect" handler. See file "helloworld.lua"
480 for a simple example or "example_application.lua" for a more complex example of
481 invocation. A table with options may be passed either as a second argument, or
482 as a first argument preceeding the callback function (whichever is more
483 convenient).
485 The following options are supported:
487 - request_body_size_limit: maximum size of payload of HTTP request body
488 (transfer encoding is allowed to add a limited amount of extra data)
489 - chunk_size: optional default value for maximum_input_chunk_size and
490 minimum_output_chunk_size
491 - request_header_size_limit: maximum size of HTTP request headers
492 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
493 certain POST fields (bigger chunks will be fragmented automatically)
494 - minimum_output_chunk_size: minimum size for a chunk when sending a response
495 body (smaller chunks will be buffered and concatenated with future data;
496 ignored when request:flush() is called)
497 - static_headers: a set of headers to be included in every HTTP response
498 (may be a string, a table or strings, or a table of key-value pairs)
500 The callback function receives a single request object as argument, which is
501 described below.
504 ### request.body
506 The request body (without headers) as a string. Accessing this value makes
507 further access to request.post_params and request.post_params_list, or
508 invocation of request:stream_request_body(...) impossible.
511 ### request:close_after_finish()
513 Closes the connection after answering the request.
515 This method can only be called before the HTTP response header section has been
516 finished (i.e. before request:finish_headers(), request:send_data(...), or
517 request:finish() were called), but it may be called before a status code has
518 been sent using request:send_status(...).
520 A corresponding "Connection: close" header is automatically sent.
522 See also request:monologue().
525 ### request:consume_input()
527 Starts processing the request body (if existent) to set the values
528 request.post_params, request.post_params_list, request.post_metadata, and
529 and request.post_metadata_list and/or to call POST field stream handlers that
530 have been previously registered with request:stream_post_param(...) or
531 request:stream_post_params(...), or to call a previously registered request
532 body stream handler that was set with request:set_request_body_streamer().
534 This method gets invoked automatically when the POST param tables
535 (request.post_params, etc.) are accessed or if request.body is accessed.
538 ### request.cookies
540 A table with all cookies sent by the client.
543 ### request.faulty
545 Normally set to false. In case of a write error on the client connection or
546 certain other unexpected errors, this value is set to true before a Lua error
547 is raised.
549 A faulty request handle must not be used, or another Lua error will be raised.
552 ### request:finish()
554 Finishes and flushes a HTTP response. An HTTP status, all headers, and the
555 response body (if applicable) must have been previously sent. May be called
556 multiple times (performs no operation if called on a finished request handle).
557 Gets automatically invoked when the callback handler returns. After calling
558 this method explicitly, no further data may be written.
561 ### request:finish_headers()
563 Finishes and flushes the HTTP response header section. May be called multiple
564 times, as long as the request is not finished completely. This method is
565 automatically invoked if the application is beginning to send a response body.
566 After calling this method, no further headers may be sent.
569 ### request:flush()
571 Flushes any pending output data. Note: In order to mark the end of a response
572 body, it is required to call request:finish().
575 ### request.fresh
577 Set to false whenever the request object has been used (e.g. data has been read
578 or sent out, or a stream handler was installed); true otherwise.
581 ### request.get_params
583 A table that maps field names to their corresponding GET value. If there are
584 several GET values with the given field name, then the first value is used.
586 Note: May be implemented through metamethods, but does support iteration
587 through pairs(...).
590 ### request.get_params_list
592 A table that maps field names to a sequence of their corresponding GET values.
594 Note: May be implemented through metamethods, but does support iteration
595 through pairs(...).
598 ### request.headers
600 A table that maps (case-insensitively) a HTTP header field name to a sequence
601 of values. For each occurrence of the respective header line, a string entry is
602 created in that sequence. Non-existent headers are mapped to an empty table.
605 ### request.headers_csv_string
607 A table that maps (case-insensitively) a HTTP header field name to a comma
608 separated string. Multiple occurrences of the header with the given field name
609 are automatically merged into the comma separated string.
612 ### request.headers_csv_table
614 A table that maps (case-insensitively) a HTTP header field name to a sequence
615 of values. One entry is created in that sequence for every comma separated
616 value of each header with the given field name.
619 ### request.headers_flags
621 A table that maps (case-insensitively) a HTTP header field name to another
622 table which (again case-insensitively) maps a string to a boolean, depending on
623 whether this string occurred in the list of comma separated values of one
624 header line with the given field name that was the key in the first table.
627 ### request.headers_value
629 A table that maps (case-insensitively) a HTTP header field name to a value. If
630 multiple header lines with the given field name have been received, false is
631 used as value.
634 ### request.method
636 The HTTP request method, e.g. "HEAD", "GET", or "POST".
639 ### request:monologue()
641 Same as request:close_after_finish() but additionally discards all input data
642 immediately.
645 ### request.path
647 The requested path without a leading slash and without the query part (e.g.
648 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
649 see request.query.
651 This value will be nil if (and only if) the request method is "OPTIONS" with a
652 request target equal to "*" (see also asterisk-form of request-target in
653 section 5.3.4 in RFC 7230).
656 ### request.post_metadata
658 Only set for multipart/form-data POST requests. A table that maps field names
659 to their corresponding POST metadata table which contains two entries:
660 "file_name" and "content_type". If there are several POST values with the given
661 field name, then the first value/file is used.
663 Note: May be implemented through metamethods, but does support iteration
664 through pairs(...).
667 ### request.post_metadata_list
669 Only set for multipart/form-data POST requests. A table that maps field names
670 to a sequence with their corresponding POST metadata tables. Needed if multiple
671 files are uploaded with the same field name.
673 Note: May be implemented through metamethods, but does support iteration
674 through pairs(...).
677 ### request.post_params
679 A table that maps field names to their corresponding POST value. If there are
680 several POST values with the given field name, then the first value is used.
682 Note: May be implemented through metamethods, but does support iteration
683 through pairs(...).
686 ### request.post_params_list
688 A table that maps field names to a sequence of their corresponding POST values.
690 Note: May be implemented through metamethods, but does support iteration
691 through pairs(...).
694 ### request.query
696 Query part of the request target including the leading question mark, e.g.
697 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
698 automatically parsed and made available through request.get_params and
699 request.get_params_list.
701 If there is no query part given in the request target, then this string is
702 the empty string. This value will be nil if (and only if) the request method
703 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
704 request-target in section 5.3.4 in RFC 7230).
707 ### request:send_data(...)
709 Sends data as response body. All arguments are converted via tostring(...) and
710 concatenated. May be called multiple times until the request has been finished
711 by calling request:finish().
713 If the request method (see request.method) is "HEAD", then calls to
714 request:send_data(...) are automatically ignored.
717 ### request:send_header(key, value)
719 Sends a HTTP response header that consists of the given key and the given
720 value. Note: Key and value must be provided as separate arguments. Before any
721 headers can be sent, a HTTP status must have been set with
722 request:send_status(status_string).
725 ### request:send_status(status_string)
727 Sends a HTTP response status that is given as a string consisting of a 3-digit
728 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
729 function must be called once before any headers or response body data may be
730 sent.
733 ### request.socket
735 The underlaying socket. Can be used to force a TCP RST, etc.
738 ### request:stream_post_param(field_name, callback)
740 Registers a stream handler for the given POST parameter. The callback function
741 will be called in the following manner:
743 - For the initial chunk, the first chunk gets passed as first argument while a
744 table with metadata ("field_name" and "content_type") gets passed as second
745 argument. In case of an immediate EOF (i.e. an empty file), the passed
746 chunk is the empty string. In all other cases the chunk has a length greater
747 than zero.
748 - For any remaining chunks, the respective chunk gets passed as first and only
749 argument (no metadata). Here, the chunk has always a length greater than
750 zero.
751 - To indicate the end of the stream, the callback function is called without
752 arguments. This also happens in case of an immediate EOF (see above).
754 In case of an immediate EOF (i.e. an empty file), the callback function is thus
755 called as follows:
757 - The first time with an empty string as first argument, and with the metadata
758 as second argument.
759 - The second time without any arguments.
761 Note that request:consume_input() needs to be called to enforce streaming to
762 finish.
765 ### request:stream_post_params(pattern, callback)
767 Same as request:stream_post_param(...) but providing a string pattern to match
768 multiple field names (e.g. "^file_[0-9]+$").
771 ### request:stream_request_body(callback)
773 Registeres a stream handler for the whole request body. For each chunk of the
774 request body, the callback function is called with the corresponding chunk. End
775 of data is indicated by passing a nil value to the callback functuion.
777 Note that request:consume_input() needs to be called to enforce streaming to
778 finish.
781 ### request:stream_request_body_now(callback)
783 Start streaming of request body immediately. On EOF the function returns and
784 the callback function is *not* called with nil as argument.