moonbridge
view reference.txt @ 75:9fff0cb4fc65
Proper handling of out-of-memory errors in xread_nb method
| author | jbe |
|---|---|
| date | Sat Apr 04 23:32:24 2015 +0200 (2015-04-04) |
| parents | 88541c2aab4d |
| children | 38e7bd13200d |
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 from the file handle
60 and the file handle's buffer is additionally tested for pending data.
62 Please note that support for non-blocking I/O operations is limited if you use
63 ordinary file handles (as Moonbridge does). It is possible, however, to wait
64 until the first byte to read is available at a file handle. For more
65 information, see socket.input:pending().
69 Socket object passed to "connect" handler
70 -----------------------------------------
72 For every incoming connection, the registered "connect" handler is called with
73 a single socket object as argument, which is described below:
76 ### socket:cancel()
78 Closes the socket connection by sending a TCP RST package if possible to
79 indicate error condition. Returns true on success, or nil plus error message in
80 case of an I/O error. Using this method on sockets that have already been
81 closed (or canceled) will throw an error.
83 Warning: Previously sent (and flushed) data may be lost during transmission.
86 ### socket:close(timeout)
88 Closes the socket connection (input and output stream) by flushing all data and
89 sending a TCP FIN package. Returns true on success, or nil plus error message
90 in case of an I/O error. Using this method on sockets that have already been
91 closed (or canceled) will throw an error.
93 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
94 depending on the particular operating system used. All pending input data
95 should have been read before calling socket:close().
97 The optional timeout parameter may be used to wait until all data has been sent
98 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
99 happens first. A timeout value of 0 or nil causes immediate return and sending
100 of pending data in background (recommended).
103 ### socket:flush()
105 Alias for socket.output:flush()
108 ### socket.input
110 Lua file handle representing the input stream of the socket connection.
111 Supports the same methods as io.open()'s return values.
114 ### socket.input:xread(maxlen, terminator)
116 Reads as many bytes until either the maximum length is reached (first argument)
117 or a terminating character (second argument as string with a length of 1) is
118 encountered. In the latter case, the terminating character will be included in
119 the result.
121 On EOF, false (as first result value) and an error message (as second result
122 value) are returned. In case of an I/O error, nil and an error message are
123 returned.
125 This method is also available for any other Lua file handle.
128 ### socket.input:xread_nb(maxlen, terminator)
130 Same as socket.input:xread(maxlen, terminator), but non-blocking. If no more
131 data can be read due to blocking, this method returns a string containing the
132 data which has already been read. If no data could be read due to blocking,
133 then an empty string is returned.
135 On EOF, false (as first result value) and an error message (as second result
136 value) are returned. In case of an I/O error, nil and an error message are
137 returned.
139 This method is also available for any other Lua file handle.
142 ### socket.interval
144 Set to the name of an interval timer if the "connect" handler was called due to
145 an elapsed interval timer. Otherwise nil.
148 ### socket:lines()
150 Alias for socket.input:lines()
153 ### socket.local_ip4
155 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
156 string.
159 ### socket.local_ip6
161 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
162 a string.
165 ### socket.local_tcpport
167 Local TCP port used for the connection.
170 ### socket.output
172 Lua file handle representing the output stream of the socket connection.
173 Supports the same methods as io.open()'s return values.
176 ### socket.output:close()
178 Performs a half-close (i.e. sends a TCP FIN package in case of a TCP socket).
180 Note: In order to shut down a TCP connection properly, it may be necessary to
181 read any pending data from socket.input before closing the socket completely
182 (e.g. with socket:close() or by returning from the connect handler). If there
183 is still incoming data, a TCP RST packet might be sent which can cause loss of
184 transmitted data.
187 ### socket.output:write_nb(...)
189 Non-blocking write. This function attempts to write as many bytes as possible,
190 returning a string containing all data that could not be written due to
191 blocking (potentially concatenating some or all remaining arguments to create
192 that string).
194 In case of an I/O error, nil (as first result value) and an error message (as
195 second result value) are returned.
197 This method is also available for any other Lua file handle.
200 ### socket:read(...)
202 Alias for socket.input:read()
205 ### socket.remote_ip4
207 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
208 a string.
211 ### socket.remote_ip6
213 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
214 a string.
217 ### socket.remote_tcpport
219 Remote TCP port used for the connection.
222 ### socket:write(...)
224 Alias for socket.output:write(...)
227 ### socket:write_nb(...)
229 Alias for socket.output:write(...)
232 ### socket:xread(maxlen, terminator)
234 Alias for socket.input:xread(...)
237 ### socket:xread_nb(maxlen, terminator)
239 Alias for socket.input:xread_nb(...)
243 HTTP module
244 -----------
246 The http module exports the function http.generate_handler(callback) that
247 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
248 example of invocation. A table with options may be passed either as a second
249 argument, or as a first argument preceeding the callback function (whichever is
250 more convenient).
252 The following options are supported:
254 - request_body_size_limit: maximum size of payload of HTTP request body
255 (transfer encoding is allowed to add a limited amount of extra data)
256 - chunk_size: optional default value for maximum_input_chunk_size and
257 minimum_output_chunk_size
258 - request_header_size_limit: maximum size of HTTP request headers
259 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
260 certain POST fields (bigger chunks will be fragmented automatically)
261 - minimum_output_chunk_size: minimum size for a chunk when sending a response
262 body (smaller chunks will be buffered and concatenated with future data;
263 ignored when request:flush() is called)
264 - static_headers: a set of headers to be included in every HTTP response
265 (may be a string, a table or strings, or a table of key-value pairs)
267 The callback function receives a single request object as argument, which is
268 described below.
271 ### request.body
273 The request body (without headers) as a string. Accessing this value makes
274 further access to request.post_params and request.post_params_list, or
275 invocation of request:stream_request_body(...) impossible.
278 ### request:close_after_finish()
280 Closes the connection after answering the request.
282 This method can only be called before the HTTP response header section has been
283 finished (i.e. before request:finish_headers(), request:send_data(...), or
284 request:finish() were called), but it may be called before a status code has
285 been sent using request:send_status(...).
287 A corresponding "Connection: close" header is automatically sent.
290 ### request.cookies
292 A table with all cookies sent by the client.
295 ### request.defer_reading()
297 Disables automatic request body processing on write. Can be called before
298 sending a HTTP status code to send a response before the request has been fully
299 received.
301 CAUTION: Responding to a request before the request body has been processed may
302 lead to a deadlock if the browser does not process the response while trying to
303 send the request. Therefore, this function should only be used if:
305 - the TCP stack has enough buffer space for the response (i.e. if the response
306 is small enough), and if
307 - a timer is used to cancel the response in case of a deadlock.
309 It is recommended to not use this function unless certain performance tweaks
310 are desired.
313 ### request.faulty
315 Normally set to false. In case of a read or write error on the client
316 connection, this value is set to true before a Lua error is raised.
318 A faulty request handle must not be used, or another Lua error will be raised.
321 ### request:finish()
323 Finishes and flushes a HTTP response. May be called multiple times. An
324 HTTP status, all headers, and the response body (if applicable) must have been
325 previously sent. After calling this method, no further data may be written.
328 ### request:finish_headers()
330 Finishes and flushes the HTTP response header section. May be called multiple
331 times, as long as the request is not finished completely. This method is
332 automatically invoked if the application is beginning to send a response body.
333 After calling this method, no further headers may be sent.
336 ### request:flush()
338 Flushes any pending output data. Note: In order to mark the end of a response
339 body, it is required to call request:finish().
342 ### request.get_params
344 A table that maps field names to their corresponding GET value. If there are
345 several GET values with the given field name, then the first value is used.
347 Note: May be implemented through metamethods, but does support iteration
348 through pairs(...).
351 ### request.get_params_list
353 A table that maps field names to a sequence of their corresponding GET values.
355 Note: May be implemented through metamethods, but does support iteration
356 through pairs(...).
359 ### request.headers
361 A table that maps (case-insensitively) a HTTP header field name to a sequence
362 of values. One entry is created for every occurrence of a header line with the
363 given field name).
366 ### request.headers_csv_string
368 A table that maps (case-insensitively) a HTTP header field name to a comma
369 separated string. Multiple occurrences of the header with the given field name
370 are automatically merged into the comma separated string.
373 ### request.headers_csv_table
375 A table that maps (case-insensitively) a HTTP header field name to a sequence
376 of values. One entry is created for every comma separated value of each header
377 with the given field name.
380 ### request.headers_flags
382 A table that maps (case-insensitively) a HTTP header field name to another
383 table which (again case-insensitively) maps a string to a boolean, depending on
384 whether this string occurred in the list of comma separated values of one
385 header line with the given field name that was the key in the first table.
388 ### request.headers_value
390 A table that maps (case-insensitively) a HTTP header field name to a value. If
391 multiple header lines with the given field name have been received, false is
392 used as value.
395 ### request.method
397 The HTTP request method, e.g. "HEAD", "GET", or "POST".
400 ### request.path
402 The requested path without a leading slash and without the query part (e.g.
403 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
404 see request.query.
406 This value will be nil if (and only if) the request method is "OPTIONS" with a
407 request target equal to "*" (see also asterisk-form of request-target in
408 section 5.3.4 in RFC 7230).
411 ### request.post_metadata
413 Only set for multipart/form-data POST requests. A table that maps field names
414 to their corresponding POST metadata table which contains two entries:
415 "file_name" and "content_type". If there are several POST values with the given
416 field name, then the first value/file is used.
419 ### request.post_metadata_list
421 Only set for multipart/form-data POST requests. A table that maps field names
422 to a sequence with their corresponding POST metadata tables. Needed if multiple
423 files are uploaded with the same field name.
426 ### request.post_params
428 A table that maps field names to their corresponding POST value. If there are
429 several POST values with the given field name, then the first value is used.
431 Note: May be implemented through metamethods, but does support iteration
432 through pairs(...).
435 ### request.post_params_list
437 A table that maps field names to a sequence of their corresponding POST values.
439 Note: May be implemented through metamethods, but does support iteration
440 through pairs(...).
443 ### request.query
445 Query part of the request target including the leading question mark, e.g.
446 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
447 automatically parsed and made available through request.get_params and
448 request.get_params_list.
450 If there is no query part given in the request target, then this string is
451 the empty string. This value will be nil if (and only if) the request method
452 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
453 request-target in section 5.3.4 in RFC 7230).
456 ### request:process_request_body()
458 Starts processing the request body (if existent) to set the values
459 request.post_params, request.post_params_list, request.post_metadata, and
460 and request.post_metadata_list and/or to call POST field stream handlers that
461 have been previously registered with request:stream_post_param(...) or
462 request:stream_post_params(...).
464 This method gets invoked automatically when the POST param tables
465 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
466 deadlocks with the webbrowser). (Note: Automatic request body processing on
467 write may be disabled by calling request:defer_reading().)
469 After this method returned, all registered POST field stream handlers have
470 received all data. Registration of other POST field stream handlers is not
471 possible after this method has been called (or after request.post_params_list
472 or request.post_params have been accessed).
475 ### request:send_data(...)
477 Sends data as response body. All arguments are converted via tostring(...) and
478 concatenated. May be called multiple times until the request has been finished
479 by calling request:finish().
481 If the request method (see request.method) is "HEAD", then calls to
482 request:send_data(...) are automatically ignored.
485 ### request:send_header(key, value)
487 Sends a HTTP response header that consists of the given key and the given
488 value. Note: Key and value must be provided as separate arguments. Before any
489 headers can be sent, a HTTP status must have been set with
490 request:send_status(status_string).
493 ### request:send_status(status_string)
495 Sends a HTTP response status that is given as a string consisting of a 3-digit
496 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
497 function must be called once before any headers or response body data may be
498 sent.
501 ### request.socket
503 The underlaying socket. Can be used to force a TCP RST, etc.
506 ### request:stream_post_param(field_name, callback)
508 Registers a stream handler for the given POST parameter. The callback function
509 will be called in the following manner:
511 - For the initial chunk, the first chunk gets passed as first argument while a
512 table with metadata ("field_name" and "content_type") gets passed as second
513 argument. In case of an immediate EOF (i.e. an empty file), the passed
514 chunk is the empty string. In all other cases the chunk has a length greater
515 than zero.
516 - For any remaining chunks, the respective chunk gets passed as first and only
517 argument (no metadata). Here, the chunk has always a length greater than
518 zero.
519 - To indicate the end of the stream, the callback function is called without
520 arguments. This also happens in case of an immediate EOF (see above).
522 In case of an immediate EOF (i.e. an empty file), the callback function is thus
523 called as follows:
525 - The first time with an empty string as first argument, and with the metadata
526 as second argument.
527 - The second time without any arguments.
530 ### request:stream_post_params(pattern, callback)
532 Same as request:stream_post_param(...) but providing a string pattern to match
533 multiple field names (e.g. "^file_[0-9]+$").
536 ### request:stream_request_body(callback)
538 Start streaming of request body. For each chunk of the request body, the
539 callback function is called with the corresponding chunk. End of data is
540 indicated through return of request:stream_request_body(...) (not by calling
541 the callback without arguments).
543 The function may be called with nil instead of a callback function. In this
544 case, the request body is read and discarded. Only if nil is passed instead of
545 a callback, then the function may also be invoked when the request body has
546 already been read and/or processed. In the latter case, the function performs
547 no operation.