moonbridge

view reference.txt @ 77:38e7bd13200d

Use write instead of fwrite for non-blocking I/O
author jbe
date Sun Apr 05 01:17:06 2015 +0200 (2015-04-05)
parents 88541c2aab4d
children 0ec070d6f5d9
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, in case of waiting for reading, the file handle's buffer is additionally
61 tested for pending data.
63 Please note that support for non-blocking I/O operations is limited if you use
64 ordinary file handles (as Moonbridge does). It is possible, however, to wait
65 until the first byte to read is available at a file handle. For more
66 information, see socket.input:pending().
70 Socket object passed to "connect" handler
71 -----------------------------------------
73 For every incoming connection, the registered "connect" handler is called with
74 a single socket object as argument, which is described below:
77 ### socket:cancel()
79 Closes the socket connection by sending a TCP RST package if possible to
80 indicate error condition. Returns true on success, or nil plus error message in
81 case of an I/O error. Using this method on sockets that have already been
82 closed (or canceled) will throw an error.
84 Warning: Previously sent (and flushed) data may be lost during transmission.
87 ### socket:close(timeout)
89 Closes the socket connection (input and output stream) by flushing all data and
90 sending a TCP FIN package. Returns true on success, or nil plus error message
91 in case of an I/O error. Using this method on sockets that have already been
92 closed (or canceled) will throw an error.
94 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
95 depending on the particular operating system used. All pending input data
96 should have been read before calling socket:close().
98 The optional timeout parameter may be used to wait until all data has been sent
99 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
100 happens first. A timeout value of 0 or nil causes immediate return and sending
101 of pending data in background (recommended).
104 ### socket:flush()
106 Alias for socket.output:flush()
109 ### socket.input
111 Lua file handle representing the input stream of the socket connection.
112 Supports the same methods as io.open()'s return values.
115 ### socket.input:xread(maxlen, terminator)
117 Reads as many bytes until either the maximum length is reached (first argument)
118 or a terminating character (second argument as string with a length of 1) is
119 encountered. In the latter case, the terminating character will be included in
120 the result.
122 On EOF, false (as first result value) and an error message (as second result
123 value) are returned. In case of an I/O error, nil and an error message are
124 returned.
126 This method is also available for any other Lua file handle.
129 ### socket.input:xread_nb(maxlen, terminator)
131 Same as socket.input:xread(maxlen, terminator), but non-blocking. If no more
132 data can be read due to blocking, this method returns a string containing the
133 data which has already been read. If no data could be read due to blocking,
134 then an empty string is returned.
136 On EOF, false (as first result value) and an error message (as second result
137 value) are returned. In case of an I/O error, nil and an error message are
138 returned.
140 This method is also available for any other Lua file handle.
143 ### socket.interval
145 Set to the name of an interval timer if the "connect" handler was called due to
146 an elapsed interval timer. Otherwise nil.
149 ### socket:lines()
151 Alias for socket.input:lines()
154 ### socket.local_ip4
156 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
157 string.
160 ### socket.local_ip6
162 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
163 a string.
166 ### socket.local_tcpport
168 Local TCP port used for the connection.
171 ### socket.output
173 Lua file handle representing the output stream of the socket connection.
174 Supports the same methods as io.open()'s return values.
177 ### socket.output:close()
179 Performs a half-close (i.e. sends a TCP FIN package in case of a TCP socket).
181 Note: In order to shut down a TCP connection properly, it may be necessary to
182 read any pending data from socket.input before closing the socket completely
183 (e.g. with socket:close() or by returning from the connect handler). If there
184 is still incoming data, a TCP RST packet might be sent which can cause loss of
185 transmitted data.
188 ### socket.output:write_nb(...)
190 Non-blocking write. This function attempts to write as many bytes as possible,
191 returning a string containing all data that could not be written due to
192 blocking (potentially concatenating some or all remaining arguments to create
193 that string).
195 In case of an I/O error, nil (as first result value) and an error message (as
196 second result value) are returned.
198 Note: Using this method will automatically flush any unflushed data written
199 through previous socket.output:write(...) calls. Thus, if any data was
200 previously written in a blocking fashion and has not been flushed, then the
201 socket.output:write_nb(...) call may block.
203 This method is also available for any other Lua file handle.
206 ### socket:read(...)
208 Alias for socket.input:read()
211 ### socket.remote_ip4
213 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
214 a string.
217 ### socket.remote_ip6
219 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
220 a string.
223 ### socket.remote_tcpport
225 Remote TCP port used for the connection.
228 ### socket:write(...)
230 Alias for socket.output:write(...)
233 ### socket:write_nb(...)
235 Alias for socket.output:write(...)
238 ### socket:xread(maxlen, terminator)
240 Alias for socket.input:xread(...)
243 ### socket:xread_nb(maxlen, terminator)
245 Alias for socket.input:xread_nb(...)
249 HTTP module
250 -----------
252 The http module exports the function http.generate_handler(callback) that
253 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
254 example of invocation. A table with options may be passed either as a second
255 argument, or as a first argument preceeding the callback function (whichever is
256 more convenient).
258 The following options are supported:
260 - request_body_size_limit: maximum size of payload of HTTP request body
261 (transfer encoding is allowed to add a limited amount of extra data)
262 - chunk_size: optional default value for maximum_input_chunk_size and
263 minimum_output_chunk_size
264 - request_header_size_limit: maximum size of HTTP request headers
265 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
266 certain POST fields (bigger chunks will be fragmented automatically)
267 - minimum_output_chunk_size: minimum size for a chunk when sending a response
268 body (smaller chunks will be buffered and concatenated with future data;
269 ignored when request:flush() is called)
270 - static_headers: a set of headers to be included in every HTTP response
271 (may be a string, a table or strings, or a table of key-value pairs)
273 The callback function receives a single request object as argument, which is
274 described below.
277 ### request.body
279 The request body (without headers) as a string. Accessing this value makes
280 further access to request.post_params and request.post_params_list, or
281 invocation of request:stream_request_body(...) impossible.
284 ### request:close_after_finish()
286 Closes the connection after answering the request.
288 This method can only be called before the HTTP response header section has been
289 finished (i.e. before request:finish_headers(), request:send_data(...), or
290 request:finish() were called), but it may be called before a status code has
291 been sent using request:send_status(...).
293 A corresponding "Connection: close" header is automatically sent.
296 ### request.cookies
298 A table with all cookies sent by the client.
301 ### request.defer_reading()
303 Disables automatic request body processing on write. Can be called before
304 sending a HTTP status code to send a response before the request has been fully
305 received.
307 CAUTION: Responding to a request before the request body has been processed may
308 lead to a deadlock if the browser does not process the response while trying to
309 send the request. Therefore, this function should only be used if:
311 - the TCP stack has enough buffer space for the response (i.e. if the response
312 is small enough), and if
313 - a timer is used to cancel the response in case of a deadlock.
315 It is recommended to not use this function unless certain performance tweaks
316 are desired.
319 ### request.faulty
321 Normally set to false. In case of a read or write error on the client
322 connection, this value is set to true before a Lua error is raised.
324 A faulty request handle must not be used, or another Lua error will be raised.
327 ### request:finish()
329 Finishes and flushes a HTTP response. May be called multiple times. An
330 HTTP status, all headers, and the response body (if applicable) must have been
331 previously sent. After calling this method, no further data may be written.
334 ### request:finish_headers()
336 Finishes and flushes the HTTP response header section. May be called multiple
337 times, as long as the request is not finished completely. This method is
338 automatically invoked if the application is beginning to send a response body.
339 After calling this method, no further headers may be sent.
342 ### request:flush()
344 Flushes any pending output data. Note: In order to mark the end of a response
345 body, it is required to call request:finish().
348 ### request.get_params
350 A table that maps field names to their corresponding GET value. If there are
351 several GET values with the given field name, then the first value is used.
353 Note: May be implemented through metamethods, but does support iteration
354 through pairs(...).
357 ### request.get_params_list
359 A table that maps field names to a sequence of their corresponding GET values.
361 Note: May be implemented through metamethods, but does support iteration
362 through pairs(...).
365 ### request.headers
367 A table that maps (case-insensitively) a HTTP header field name to a sequence
368 of values. One entry is created for every occurrence of a header line with the
369 given field name).
372 ### request.headers_csv_string
374 A table that maps (case-insensitively) a HTTP header field name to a comma
375 separated string. Multiple occurrences of the header with the given field name
376 are automatically merged into the comma separated string.
379 ### request.headers_csv_table
381 A table that maps (case-insensitively) a HTTP header field name to a sequence
382 of values. One entry is created for every comma separated value of each header
383 with the given field name.
386 ### request.headers_flags
388 A table that maps (case-insensitively) a HTTP header field name to another
389 table which (again case-insensitively) maps a string to a boolean, depending on
390 whether this string occurred in the list of comma separated values of one
391 header line with the given field name that was the key in the first table.
394 ### request.headers_value
396 A table that maps (case-insensitively) a HTTP header field name to a value. If
397 multiple header lines with the given field name have been received, false is
398 used as value.
401 ### request.method
403 The HTTP request method, e.g. "HEAD", "GET", or "POST".
406 ### request.path
408 The requested path without a leading slash and without the query part (e.g.
409 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
410 see request.query.
412 This value will be nil if (and only if) the request method is "OPTIONS" with a
413 request target equal to "*" (see also asterisk-form of request-target in
414 section 5.3.4 in RFC 7230).
417 ### request.post_metadata
419 Only set for multipart/form-data POST requests. A table that maps field names
420 to their corresponding POST metadata table which contains two entries:
421 "file_name" and "content_type". If there are several POST values with the given
422 field name, then the first value/file is used.
425 ### request.post_metadata_list
427 Only set for multipart/form-data POST requests. A table that maps field names
428 to a sequence with their corresponding POST metadata tables. Needed if multiple
429 files are uploaded with the same field name.
432 ### request.post_params
434 A table that maps field names to their corresponding POST value. If there are
435 several POST values with the given field name, then the first value is used.
437 Note: May be implemented through metamethods, but does support iteration
438 through pairs(...).
441 ### request.post_params_list
443 A table that maps field names to a sequence of their corresponding POST values.
445 Note: May be implemented through metamethods, but does support iteration
446 through pairs(...).
449 ### request.query
451 Query part of the request target including the leading question mark, e.g.
452 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
453 automatically parsed and made available through request.get_params and
454 request.get_params_list.
456 If there is no query part given in the request target, then this string is
457 the empty string. This value will be nil if (and only if) the request method
458 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
459 request-target in section 5.3.4 in RFC 7230).
462 ### request:process_request_body()
464 Starts processing the request body (if existent) to set the values
465 request.post_params, request.post_params_list, request.post_metadata, and
466 and request.post_metadata_list and/or to call POST field stream handlers that
467 have been previously registered with request:stream_post_param(...) or
468 request:stream_post_params(...).
470 This method gets invoked automatically when the POST param tables
471 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
472 deadlocks with the webbrowser). (Note: Automatic request body processing on
473 write may be disabled by calling request:defer_reading().)
475 After this method returned, all registered POST field stream handlers have
476 received all data. Registration of other POST field stream handlers is not
477 possible after this method has been called (or after request.post_params_list
478 or request.post_params have been accessed).
481 ### request:send_data(...)
483 Sends data as response body. All arguments are converted via tostring(...) and
484 concatenated. May be called multiple times until the request has been finished
485 by calling request:finish().
487 If the request method (see request.method) is "HEAD", then calls to
488 request:send_data(...) are automatically ignored.
491 ### request:send_header(key, value)
493 Sends a HTTP response header that consists of the given key and the given
494 value. Note: Key and value must be provided as separate arguments. Before any
495 headers can be sent, a HTTP status must have been set with
496 request:send_status(status_string).
499 ### request:send_status(status_string)
501 Sends a HTTP response status that is given as a string consisting of a 3-digit
502 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
503 function must be called once before any headers or response body data may be
504 sent.
507 ### request.socket
509 The underlaying socket. Can be used to force a TCP RST, etc.
512 ### request:stream_post_param(field_name, callback)
514 Registers a stream handler for the given POST parameter. The callback function
515 will be called in the following manner:
517 - For the initial chunk, the first chunk gets passed as first argument while a
518 table with metadata ("field_name" and "content_type") gets passed as second
519 argument. In case of an immediate EOF (i.e. an empty file), the passed
520 chunk is the empty string. In all other cases the chunk has a length greater
521 than zero.
522 - For any remaining chunks, the respective chunk gets passed as first and only
523 argument (no metadata). Here, the chunk has always a length greater than
524 zero.
525 - To indicate the end of the stream, the callback function is called without
526 arguments. This also happens in case of an immediate EOF (see above).
528 In case of an immediate EOF (i.e. an empty file), the callback function is thus
529 called as follows:
531 - The first time with an empty string as first argument, and with the metadata
532 as second argument.
533 - The second time without any arguments.
536 ### request:stream_post_params(pattern, callback)
538 Same as request:stream_post_param(...) but providing a string pattern to match
539 multiple field names (e.g. "^file_[0-9]+$").
542 ### request:stream_request_body(callback)
544 Start streaming of request body. For each chunk of the request body, the
545 callback function is called with the corresponding chunk. End of data is
546 indicated through return of request:stream_request_body(...) (not by calling
547 the callback without arguments).
549 The function may be called with nil instead of a callback function. In this
550 case, the request body is read and discarded. Only if nil is passed instead of
551 a callback, then the function may also be invoked when the request body has
552 already been read and/or processed. In the latter case, the function performs
553 no operation.

Impressum / About Us