moonbridge
view reference.txt @ 91:6b26783f9323
write_nb returns total number of bytes buffered in case of block; Updated reference
| author | jbe |
|---|---|
| date | Tue Apr 07 03:50:28 2015 +0200 (2015-04-07) |
| parents | 0ec070d6f5d9 |
| children | de0e69673953 |
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(timeout)
57 Closes the socket connection (input and output stream) by flushing all data and
58 sending a TCP FIN packet. If the timeout value is non-nil but zero, a TCP RST
59 is sent instead. If a positive timeout value is given and if the remote peer
60 doesn't respond with a TCP FIN within the given time, a TCP RST is sent in
61 addition to the previously sent TCP FIN packet. If the timeout value is nil or
62 negative, the call returns immediately and the operating system will wait for
63 the peer's TCP FIN packet.
65 Returns true on success, or nil plus error message in case of an I/O error.
66 Using this method on sockets that have already been closed (or reset) will
67 throw an error.
69 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
70 depending on the particular operating system used. All pending input data
71 should have been read (or drained) before calling socket:close().
74 ### socket:drain(maxlen, terminator)
76 Same as socket:read(maxlen, terminator), but discards the input and returns the
77 number of discarded bytes. If no bytes could be read but EOF was encountered,
78 then true is returned.
80 In case of an I/O error, nil (as first return value) plus an error message (as
81 second result value) are returned.
84 ### socket:drain_nb(maxlen, terminator)
86 Same as socket:read_nb(maxlen, terminator), but discards the input and returns
87 the number of discarded bytes. If no bytes could be read but EOF was
88 encountered, then true is returned.
90 In case of an I/O error, nil (as first return value) plus an error message (as
91 second result value) are returned.
95 ### socket:flush(...)
97 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
98 data is passed to the operating system).
100 In case of an I/O error, nil (as first return value) plus an error message (as
101 second result value) are returned. On success, the socket userdata object is
102 returned.
105 ### socket:flush_nb(...)
107 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
108 pending data is passed to the operating system). The total number of bytes that
109 could not be passed yet to the operating system is returned. Zero is returned
110 if all data could be flushed out.
112 In case of an I/O error, nil (as first return value) plus an error message (as
113 second result value) are returned.
116 ### socket.interval
118 Set to the name of an interval timer if the "connect" handler was called due to
119 an elapsed interval timer. Otherwise nil.
122 ### socket.local_ip4
124 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
125 string.
128 ### socket.local_ip6
130 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
131 a string.
134 ### socket.local_tcpport
136 Local TCP port used for the connection.
139 ### socket:read(maxlen, terminator)
141 Read up to maxlen bytes or until an optional termination character is
142 encountered (which is included in the result). The maxlen value may be nil, in
143 which case there is no limit on the number of bytes read.
145 If EOF is encountered before any data could be read, then false (as first
146 return value) plus a notice string (as second return value) are returned.
148 In case of an I/O error, nil (as first return value) plus an error message (as
149 second result value) are returned.
152 ### socket:read_nb(maxlen, terminator)
154 Read up to maxlen bytes, until an optional termination character is encountered
155 (which is included in the result), or until no more data is available for
156 reading. The maxlen value may be nil, in which case there is no limit on the
157 number of bytes read.
159 If EOF is encountered before any data could be read, then false (as first
160 return value) plus a notice string (as second return value) are returned.
162 If no data was available for reading, but no EOF was encountered, then an empty
163 string is returned.
165 In case of an I/O error, nil (as first return value) plus an error message (as
166 second result value) are returned.
169 ### socket.remote_ip4
171 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
172 a string.
175 ### socket.remote_ip6
177 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
178 a string.
181 ### socket.remote_tcpport
183 Remote TCP port used for the connection.
186 ### socket:reset()
188 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
189 packet if possible to indicate error condition.
191 Returns true on success, or nil (as first result value) plus error message (as
192 second result value) in case of an I/O error. Using this method on sockets that
193 have already been closed (or reset) will throw an error.
195 Warning: Previously sent (and flushed) data may be lost during transmission.
198 ### socket:write(...)
200 Takes a variable number of strings and sends them to the peer. The operation is
201 buffered, so to actually send out the data, it is necessary to eventually call
202 socket:flush(), socket:finish(), or socket:close().
204 In case of an I/O error, nil (as first return value) plus an error message (as
205 second result value) are returned. On success, the socket userdata object is
206 returned.
209 ### socket:write_nb(...)
211 Takes a variable number of strings and sends them to the peer. The operation is
212 buffered, so to actually send out the data, it is necessary to eventually call
213 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
215 This function always returns immediately (i.e. it does not block). If all data
216 (but a small buffered portion) could be sent out, then zero is returned.
217 Otherwise, all arguments that could not be sent are stored in a buffer of
218 unlimited size (up to memory capabilities) and an integer is returned that
219 indicates the number of bytes currently in the buffer.
221 In case of an I/O error, nil (as first return value) plus an error message (as
222 second result value) are returned.
226 HTTP module
227 -----------
229 The http module exports the function http.generate_handler(callback) that
230 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
231 example of invocation. A table with options may be passed either as a second
232 argument, or as a first argument preceeding the callback function (whichever is
233 more convenient).
235 The following options are supported:
237 - request_body_size_limit: maximum size of payload of HTTP request body
238 (transfer encoding is allowed to add a limited amount of extra data)
239 - chunk_size: optional default value for maximum_input_chunk_size and
240 minimum_output_chunk_size
241 - request_header_size_limit: maximum size of HTTP request headers
242 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
243 certain POST fields (bigger chunks will be fragmented automatically)
244 - minimum_output_chunk_size: minimum size for a chunk when sending a response
245 body (smaller chunks will be buffered and concatenated with future data;
246 ignored when request:flush() is called)
247 - static_headers: a set of headers to be included in every HTTP response
248 (may be a string, a table or strings, or a table of key-value pairs)
250 The callback function receives a single request object as argument, which is
251 described below.
254 ### request.body
256 The request body (without headers) as a string. Accessing this value makes
257 further access to request.post_params and request.post_params_list, or
258 invocation of request:stream_request_body(...) impossible.
261 ### request:close_after_finish()
263 Closes the connection after answering the request.
265 This method can only be called before the HTTP response header section has been
266 finished (i.e. before request:finish_headers(), request:send_data(...), or
267 request:finish() were called), but it may be called before a status code has
268 been sent using request:send_status(...).
270 A corresponding "Connection: close" header is automatically sent.
273 ### request.cookies
275 A table with all cookies sent by the client.
278 ### request.defer_reading()
280 Disables automatic request body processing on write. Can be called before
281 sending a HTTP status code to send a response before the request has been fully
282 received.
284 CAUTION: Responding to a request before the request body has been processed may
285 lead to a deadlock if the browser does not process the response while trying to
286 send the request. Therefore, this function should only be used if:
288 - the TCP stack has enough buffer space for the response (i.e. if the response
289 is small enough), and if
290 - a timer is used to cancel the response in case of a deadlock.
292 It is recommended to not use this function unless certain performance tweaks
293 are desired.
296 ### request.faulty
298 Normally set to false. In case of a read or write error on the client
299 connection, this value is set to true before a Lua error is raised.
301 A faulty request handle must not be used, or another Lua error will be raised.
304 ### request:finish()
306 Finishes and flushes a HTTP response. May be called multiple times. An
307 HTTP status, all headers, and the response body (if applicable) must have been
308 previously sent. After calling this method, no further data may be written.
311 ### request:finish_headers()
313 Finishes and flushes the HTTP response header section. May be called multiple
314 times, as long as the request is not finished completely. This method is
315 automatically invoked if the application is beginning to send a response body.
316 After calling this method, no further headers may be sent.
319 ### request:flush()
321 Flushes any pending output data. Note: In order to mark the end of a response
322 body, it is required to call request:finish().
325 ### request.get_params
327 A table that maps field names to their corresponding GET value. If there are
328 several GET values with the given field name, then the first value is used.
330 Note: May be implemented through metamethods, but does support iteration
331 through pairs(...).
334 ### request.get_params_list
336 A table that maps field names to a sequence of their corresponding GET values.
338 Note: May be implemented through metamethods, but does support iteration
339 through pairs(...).
342 ### request.headers
344 A table that maps (case-insensitively) a HTTP header field name to a sequence
345 of values. One entry is created for every occurrence of a header line with the
346 given field name).
349 ### request.headers_csv_string
351 A table that maps (case-insensitively) a HTTP header field name to a comma
352 separated string. Multiple occurrences of the header with the given field name
353 are automatically merged into the comma separated string.
356 ### request.headers_csv_table
358 A table that maps (case-insensitively) a HTTP header field name to a sequence
359 of values. One entry is created for every comma separated value of each header
360 with the given field name.
363 ### request.headers_flags
365 A table that maps (case-insensitively) a HTTP header field name to another
366 table which (again case-insensitively) maps a string to a boolean, depending on
367 whether this string occurred in the list of comma separated values of one
368 header line with the given field name that was the key in the first table.
371 ### request.headers_value
373 A table that maps (case-insensitively) a HTTP header field name to a value. If
374 multiple header lines with the given field name have been received, false is
375 used as value.
378 ### request.method
380 The HTTP request method, e.g. "HEAD", "GET", or "POST".
383 ### request.path
385 The requested path without a leading slash and without the query part (e.g.
386 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
387 see request.query.
389 This value will be nil if (and only if) the request method is "OPTIONS" with a
390 request target equal to "*" (see also asterisk-form of request-target in
391 section 5.3.4 in RFC 7230).
394 ### request.post_metadata
396 Only set for multipart/form-data POST requests. A table that maps field names
397 to their corresponding POST metadata table which contains two entries:
398 "file_name" and "content_type". If there are several POST values with the given
399 field name, then the first value/file is used.
402 ### request.post_metadata_list
404 Only set for multipart/form-data POST requests. A table that maps field names
405 to a sequence with their corresponding POST metadata tables. Needed if multiple
406 files are uploaded with the same field name.
409 ### request.post_params
411 A table that maps field names to their corresponding POST value. If there are
412 several POST values with the given field name, then the first value is used.
414 Note: May be implemented through metamethods, but does support iteration
415 through pairs(...).
418 ### request.post_params_list
420 A table that maps field names to a sequence of their corresponding POST values.
422 Note: May be implemented through metamethods, but does support iteration
423 through pairs(...).
426 ### request.query
428 Query part of the request target including the leading question mark, e.g.
429 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
430 automatically parsed and made available through request.get_params and
431 request.get_params_list.
433 If there is no query part given in the request target, then this string is
434 the empty string. This value will be nil if (and only if) the request method
435 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
436 request-target in section 5.3.4 in RFC 7230).
439 ### request:process_request_body()
441 Starts processing the request body (if existent) to set the values
442 request.post_params, request.post_params_list, request.post_metadata, and
443 and request.post_metadata_list and/or to call POST field stream handlers that
444 have been previously registered with request:stream_post_param(...) or
445 request:stream_post_params(...).
447 This method gets invoked automatically when the POST param tables
448 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
449 deadlocks with the webbrowser). (Note: Automatic request body processing on
450 write may be disabled by calling request:defer_reading().)
452 After this method returned, all registered POST field stream handlers have
453 received all data. Registration of other POST field stream handlers is not
454 possible after this method has been called (or after request.post_params_list
455 or request.post_params have been accessed).
458 ### request:send_data(...)
460 Sends data as response body. All arguments are converted via tostring(...) and
461 concatenated. May be called multiple times until the request has been finished
462 by calling request:finish().
464 If the request method (see request.method) is "HEAD", then calls to
465 request:send_data(...) are automatically ignored.
468 ### request:send_header(key, value)
470 Sends a HTTP response header that consists of the given key and the given
471 value. Note: Key and value must be provided as separate arguments. Before any
472 headers can be sent, a HTTP status must have been set with
473 request:send_status(status_string).
476 ### request:send_status(status_string)
478 Sends a HTTP response status that is given as a string consisting of a 3-digit
479 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
480 function must be called once before any headers or response body data may be
481 sent.
484 ### request.socket
486 The underlaying socket. Can be used to force a TCP RST, etc.
489 ### request:stream_post_param(field_name, callback)
491 Registers a stream handler for the given POST parameter. The callback function
492 will be called in the following manner:
494 - For the initial chunk, the first chunk gets passed as first argument while a
495 table with metadata ("field_name" and "content_type") gets passed as second
496 argument. In case of an immediate EOF (i.e. an empty file), the passed
497 chunk is the empty string. In all other cases the chunk has a length greater
498 than zero.
499 - For any remaining chunks, the respective chunk gets passed as first and only
500 argument (no metadata). Here, the chunk has always a length greater than
501 zero.
502 - To indicate the end of the stream, the callback function is called without
503 arguments. This also happens in case of an immediate EOF (see above).
505 In case of an immediate EOF (i.e. an empty file), the callback function is thus
506 called as follows:
508 - The first time with an empty string as first argument, and with the metadata
509 as second argument.
510 - The second time without any arguments.
513 ### request:stream_post_params(pattern, callback)
515 Same as request:stream_post_param(...) but providing a string pattern to match
516 multiple field names (e.g. "^file_[0-9]+$").
519 ### request:stream_request_body(callback)
521 Start streaming of request body. For each chunk of the request body, the
522 callback function is called with the corresponding chunk. End of data is
523 indicated through return of request:stream_request_body(...) (not by calling
524 the callback without arguments).
526 The function may be called with nil instead of a callback function. In this
527 case, the request body is read and discarded. Only if nil is passed instead of
528 a callback, then the function may also be invoked when the request body has
529 already been read and/or processed. In the latter case, the function performs
530 no operation.