moonbridge

view reference.txt @ 116:2ab19e15aa6b

Proper marking I/O handles as closed and finished
author jbe
date Fri Apr 10 02:24:54 2015 +0200 (2015-04-10)
parents 0eba766e9be2
children 118e320a7812
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. If no bytes could be read but EOF was encountered,
74 then true is returned.
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_nb(maxlen, terminator)
82 Same as socket:read_nb(maxlen, terminator), but discards the input and returns
83 the number of discarded bytes. If no bytes could be read but EOF was
84 encountered, then true is returned.
86 In case of an I/O error, nil (as first return value) plus an error message (as
87 second return value) are returned.
90 ### socket:finish()
92 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
93 still possible. When there is no more input data to be read, the connection
94 should finally be closed with socket:close().
96 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
97 the underlying socket and emulates EOF on subsequent reads. Also in this case,
98 the connection should be finally closed with socket:close().
101 ### socket:flush(...)
103 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
104 data is passed to the operating system).
106 In case of an I/O error, nil (as first return value) plus an error message (as
107 second return value) are returned. On success, the socket userdata object is
108 returned.
111 ### socket:flush_nb(...)
113 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
114 pending data is passed to the operating system). The total number of bytes that
115 could not be passed yet to the operating system is returned. Zero is returned
116 if all data could be flushed out.
118 In case of an I/O error, nil (as first return value) plus an error message (as
119 second return value) are returned.
122 ### socket.interval
124 Set to the name of an interval timer if the "connect" handler was called due to
125 an elapsed interval timer. Otherwise nil.
128 ### socket.local_ip4
130 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
131 string.
134 ### socket.local_ip6
136 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
137 a string.
140 ### socket.local_tcpport
142 Local TCP port used for the connection.
145 ### socket:read(maxlen, terminator)
147 Read up to maxlen bytes or until an optional termination character is
148 encountered (which is included in the result). The maxlen value may be nil, in
149 which case there is no limit on the number of bytes read.
151 If EOF is encountered before any data could be read, then false (as first
152 return value) plus a notice string (as second return value) are returned.
154 In case of an I/O error, nil (as first return value) plus an error message (as
155 second return value) are returned.
158 ### socket:read_nb(maxlen, terminator)
160 Read up to maxlen bytes, until an optional termination character is encountered
161 (which is included in the result), or until no more data is available for
162 reading. The maxlen value may be nil, in which case there is no limit on the
163 number of bytes read.
165 If EOF is encountered before any data could be read, then false (as first
166 return value) plus a notice string (as second return value) are returned.
168 If no data was available for reading, but no EOF was encountered, then an empty
169 string is returned.
171 In case of an I/O error, nil (as first return value) plus an error message (as
172 second return value) are returned.
175 ### socket.remote_ip4
177 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
178 a string.
181 ### socket.remote_ip6
183 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
184 a string.
187 ### socket.remote_tcpport
189 Remote TCP port used for the connection.
192 ### socket:reset()
194 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
195 packet if possible to indicate error condition.
197 Returns true on success, or nil (as first return value) plus error message (as
198 second return value) in case of an I/O error. Using this method on sockets that
199 have already been closed (or reset) will throw an error.
201 Warning: Previously sent (and flushed) data may be lost during transmission.
204 ### socket:write(...)
206 Takes a variable number of strings and sends them to the peer. The operation is
207 buffered, so to actually send out the data, it is necessary to eventually call
208 socket:flush(), socket:finish(), or socket:close().
210 In case of an I/O error, nil (as first return value) plus an error message (as
211 second return value) are returned. On success, the socket userdata object is
212 returned.
215 ### socket:write_nb(...)
217 Takes a variable number of strings and sends them to the peer. The operation is
218 buffered, so to actually send out the data, it is necessary to eventually call
219 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
221 This function always returns immediately (i.e. it does not block). If all data
222 (but a small buffered portion) could be sent out, then zero is returned.
223 Otherwise, all arguments that could not be sent are stored in a buffer of
224 unlimited size (up to memory capabilities) and an integer is returned that
225 indicates the number of bytes currently in the buffer.
227 In case of an I/O error, nil (as first return value) plus an error message (as
228 second return value) are returned.
232 I/O library
233 -----------
235 The Moonbridge Network Server for Lua Applications comes with its own I/O
236 library to support blocking as well as nonblocking I/O operations.
238 All methods on an I/O handle (e.g. socket) are described in the previous
239 section regarding the "socket" object. All other functions of the library are
240 listed below.
243 ### moonbridge_io.localconnect(path)
245 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
246 a socket object on success, or nil (as first return value) plus an error
247 message (as second return value) in case of error.
250 ### moonbridge_io.localconnect_nb(path)
252 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
253 a socket object on success, or nil (as first return value) plus an error
254 message (as second return value) in case of error.
256 Same as moonbridge_io.localconnect(path), except that this function does not
257 block and immediately returns a socket object.
259 In case of an I/O error, nil (as first return value) plus an error message (as
260 second return value) may be returned. However, connection errors may also be
261 reported on first read or write on the socket.
264 ### moonbridge_io.locallisten(path)
266 Attempts to create a local socket (also known as Unix Domain Socket) to accept
267 incoming connections.
269 Note: The caller is responsible for unlinking the socket in the filesystem
270 before opening or after closing the listening socket. If a file (or socket)
271 already exists at the given path, this function returns with an I/O error.
273 In case of an I/O error, nil (as first return value) plus an error message (as
274 second return value) may be returned.On success, a listener object is returned
275 which supports the methods :accept(), :accept_nb(), and :close().
277 The method :accept() blocks until a new incoming connection is available in
278 which case a socket object is returned.
280 The method :accept_nb() works like :accept(), except that the call is
281 nonblocking and returns false (plus a notice as second return value) in case no
282 incoming connection is available. It is possible to wait for an incoming
283 connection by including the listener object in the input_set of the
284 moonbridge_io.poll(...) call.
286 The method :close() will close the listening socket. In case of local sockets
287 (Unix Domain Sockets), the socket will not be unlinked in the file system.
289 I/O errors by the methods of the listener object are also reported by returning
290 nil (as first return value) plus an error message (as second return value).
293 ### moonbridge_io.poll(input_set, output_set, timeout)
295 This function waits for at least one of the given file descriptors and/or
296 I/O handles to be ready for input or output. The two sets of file descriptors
297 and/or handles must contain the file descriptor or handle as a key, and a value
298 which does evaluate to true. If a set is nil, it is treated as being empty.
300 Returns true when at least one file descriptor or handle is ready for reading
301 or writing respectively. Returns false (as first return value) plus a status
302 message (as second return value) in case of timeout or when a signal was
303 received.
306 ### moonbridge_io.tcpconnect(hostname, port)
308 Tries to open a TCP connection with the given host and TCP port number. Returns
309 a socket object on success, or nil (as first return value) plus an error
310 message (as second return value) in case of error.
313 ### moonbridge_io.tcpconnect_nb(hostname, port)
315 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
316 does not block and immediately returns a socket object.
318 Note: The current implementation still blocks during the DNS lookup. Use a
319 numeric IP address as hostname to be truly nonblocking.
321 In case of an I/O error, nil (as first return value) plus an error message (as
322 second return value) may be returned. However, connection errors may also be
323 reported on first read or write on the socket.
326 ### moonbridge_io.tcplisten(hostname, port)
328 Attempts to open a TCP port for listening. To listen on the loopback interface,
329 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
330 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
331 "0.0.0.0" (IPv4) respectively.
333 In case of an I/O error, nil (as first return value) plus an error message (as
334 second return value) may be returned. On success, a listener object is returned
335 which supports the methods :accept(), :accept_nb(), and :close(). See reference
336 for moonbridge.io_locallisten(...).
340 HTTP module
341 -----------
343 The http module exports the function http.generate_handler(callback) that
344 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
345 example of invocation. A table with options may be passed either as a second
346 argument, or as a first argument preceeding the callback function (whichever is
347 more convenient).
349 The following options are supported:
351 - request_body_size_limit: maximum size of payload of HTTP request body
352 (transfer encoding is allowed to add a limited amount of extra data)
353 - chunk_size: optional default value for maximum_input_chunk_size and
354 minimum_output_chunk_size
355 - request_header_size_limit: maximum size of HTTP request headers
356 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
357 certain POST fields (bigger chunks will be fragmented automatically)
358 - minimum_output_chunk_size: minimum size for a chunk when sending a response
359 body (smaller chunks will be buffered and concatenated with future data;
360 ignored when request:flush() is called)
361 - static_headers: a set of headers to be included in every HTTP response
362 (may be a string, a table or strings, or a table of key-value pairs)
364 The callback function receives a single request object as argument, which is
365 described below.
368 ### request.body
370 The request body (without headers) as a string. Accessing this value makes
371 further access to request.post_params and request.post_params_list, or
372 invocation of request:stream_request_body(...) impossible.
375 ### request:close_after_finish()
377 Closes the connection after answering the request.
379 This method can only be called before the HTTP response header section has been
380 finished (i.e. before request:finish_headers(), request:send_data(...), or
381 request:finish() were called), but it may be called before a status code has
382 been sent using request:send_status(...).
384 A corresponding "Connection: close" header is automatically sent.
387 ### request.cookies
389 A table with all cookies sent by the client.
392 ### request.defer_reading()
394 Disables automatic request body processing on write. Can be called before
395 sending a HTTP status code to send a response before the request has been fully
396 received.
398 CAUTION: Responding to a request before the request body has been processed may
399 lead to a deadlock if the browser does not process the response while trying to
400 send the request. Therefore, this function should only be used if:
402 - the TCP stack has enough buffer space for the response (i.e. if the response
403 is small enough), and if
404 - a timer is used to cancel the response in case of a deadlock.
406 It is recommended to not use this function unless certain performance tweaks
407 are desired.
410 ### request.faulty
412 Normally set to false. In case of a read or write error on the client
413 connection, this value is set to true before a Lua error is raised.
415 A faulty request handle must not be used, or another Lua error will be raised.
418 ### request:finish()
420 Finishes and flushes a HTTP response. May be called multiple times. An
421 HTTP status, all headers, and the response body (if applicable) must have been
422 previously sent. After calling this method, no further data may be written.
425 ### request:finish_headers()
427 Finishes and flushes the HTTP response header section. May be called multiple
428 times, as long as the request is not finished completely. This method is
429 automatically invoked if the application is beginning to send a response body.
430 After calling this method, no further headers may be sent.
433 ### request:flush()
435 Flushes any pending output data. Note: In order to mark the end of a response
436 body, it is required to call request:finish().
439 ### request.get_params
441 A table that maps field names to their corresponding GET value. If there are
442 several GET values with the given field name, then the first value is used.
444 Note: May be implemented through metamethods, but does support iteration
445 through pairs(...).
448 ### request.get_params_list
450 A table that maps field names to a sequence of their corresponding GET values.
452 Note: May be implemented through metamethods, but does support iteration
453 through pairs(...).
456 ### request.headers
458 A table that maps (case-insensitively) a HTTP header field name to a sequence
459 of values. One entry is created for every occurrence of a header line with the
460 given field name).
463 ### request.headers_csv_string
465 A table that maps (case-insensitively) a HTTP header field name to a comma
466 separated string. Multiple occurrences of the header with the given field name
467 are automatically merged into the comma separated string.
470 ### request.headers_csv_table
472 A table that maps (case-insensitively) a HTTP header field name to a sequence
473 of values. One entry is created for every comma separated value of each header
474 with the given field name.
477 ### request.headers_flags
479 A table that maps (case-insensitively) a HTTP header field name to another
480 table which (again case-insensitively) maps a string to a boolean, depending on
481 whether this string occurred in the list of comma separated values of one
482 header line with the given field name that was the key in the first table.
485 ### request.headers_value
487 A table that maps (case-insensitively) a HTTP header field name to a value. If
488 multiple header lines with the given field name have been received, false is
489 used as value.
492 ### request.method
494 The HTTP request method, e.g. "HEAD", "GET", or "POST".
497 ### request.path
499 The requested path without a leading slash and without the query part (e.g.
500 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
501 see request.query.
503 This value will be nil if (and only if) the request method is "OPTIONS" with a
504 request target equal to "*" (see also asterisk-form of request-target in
505 section 5.3.4 in RFC 7230).
508 ### request.post_metadata
510 Only set for multipart/form-data POST requests. A table that maps field names
511 to their corresponding POST metadata table which contains two entries:
512 "file_name" and "content_type". If there are several POST values with the given
513 field name, then the first value/file is used.
516 ### request.post_metadata_list
518 Only set for multipart/form-data POST requests. A table that maps field names
519 to a sequence with their corresponding POST metadata tables. Needed if multiple
520 files are uploaded with the same field name.
523 ### request.post_params
525 A table that maps field names to their corresponding POST value. If there are
526 several POST values with the given field name, then the first value is used.
528 Note: May be implemented through metamethods, but does support iteration
529 through pairs(...).
532 ### request.post_params_list
534 A table that maps field names to a sequence of their corresponding POST values.
536 Note: May be implemented through metamethods, but does support iteration
537 through pairs(...).
540 ### request.query
542 Query part of the request target including the leading question mark, e.g.
543 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
544 automatically parsed and made available through request.get_params and
545 request.get_params_list.
547 If there is no query part given in the request target, then this string is
548 the empty string. This value will be nil if (and only if) the request method
549 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
550 request-target in section 5.3.4 in RFC 7230).
553 ### request:process_request_body()
555 Starts processing the request body (if existent) to set the values
556 request.post_params, request.post_params_list, request.post_metadata, and
557 and request.post_metadata_list and/or to call POST field stream handlers that
558 have been previously registered with request:stream_post_param(...) or
559 request:stream_post_params(...).
561 This method gets invoked automatically when the POST param tables
562 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
563 deadlocks with the webbrowser). (Note: Automatic request body processing on
564 write may be disabled by calling request:defer_reading().)
566 After this method returned, all registered POST field stream handlers have
567 received all data. Registration of other POST field stream handlers is not
568 possible after this method has been called (or after request.post_params_list
569 or request.post_params have been accessed).
572 ### request:send_data(...)
574 Sends data as response body. All arguments are converted via tostring(...) and
575 concatenated. May be called multiple times until the request has been finished
576 by calling request:finish().
578 If the request method (see request.method) is "HEAD", then calls to
579 request:send_data(...) are automatically ignored.
582 ### request:send_header(key, value)
584 Sends a HTTP response header that consists of the given key and the given
585 value. Note: Key and value must be provided as separate arguments. Before any
586 headers can be sent, a HTTP status must have been set with
587 request:send_status(status_string).
590 ### request:send_status(status_string)
592 Sends a HTTP response status that is given as a string consisting of a 3-digit
593 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
594 function must be called once before any headers or response body data may be
595 sent.
598 ### request.socket
600 The underlaying socket. Can be used to force a TCP RST, etc.
603 ### request:stream_post_param(field_name, callback)
605 Registers a stream handler for the given POST parameter. The callback function
606 will be called in the following manner:
608 - For the initial chunk, the first chunk gets passed as first argument while a
609 table with metadata ("field_name" and "content_type") gets passed as second
610 argument. In case of an immediate EOF (i.e. an empty file), the passed
611 chunk is the empty string. In all other cases the chunk has a length greater
612 than zero.
613 - For any remaining chunks, the respective chunk gets passed as first and only
614 argument (no metadata). Here, the chunk has always a length greater than
615 zero.
616 - To indicate the end of the stream, the callback function is called without
617 arguments. This also happens in case of an immediate EOF (see above).
619 In case of an immediate EOF (i.e. an empty file), the callback function is thus
620 called as follows:
622 - The first time with an empty string as first argument, and with the metadata
623 as second argument.
624 - The second time without any arguments.
627 ### request:stream_post_params(pattern, callback)
629 Same as request:stream_post_param(...) but providing a string pattern to match
630 multiple field names (e.g. "^file_[0-9]+$").
633 ### request:stream_request_body(callback)
635 Start streaming of request body. For each chunk of the request body, the
636 callback function is called with the corresponding chunk. End of data is
637 indicated through return of request:stream_request_body(...) (not by calling
638 the callback without arguments).
640 The function may be called with nil instead of a callback function. In this
641 case, the request body is read and discarded. Only if nil is passed instead of
642 a callback, then the function may also be invoked when the request body has
643 already been read and/or processed. In the latter case, the function performs
644 no operation.

Impressum / About Us