moonbridge

view reference.txt @ 84:8a6e2a80fcad

Refined interface of I/O library to directly support (previously opened) sockets
author jbe
date Mon Apr 06 15:41:37 2015 +0200 (2015-04-06)
parents 0ec070d6f5d9
children 6b26783f9323
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:cancel()
57 Closes the socket connection by sending a TCP RST package if possible to
58 indicate error condition. Returns true on success, or nil plus error message in
59 case of an I/O error. Using this method on sockets that have already been
60 closed (or canceled) will throw an error.
62 Warning: Previously sent (and flushed) data may be lost during transmission.
65 ### socket:close(timeout)
67 Closes the socket connection (input and output stream) by flushing all data and
68 sending a TCP FIN package. Returns true on success, or nil plus error message
69 in case of an I/O error. Using this method on sockets that have already been
70 closed (or canceled) will throw an error.
72 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
73 depending on the particular operating system used. All pending input data
74 should have been read before calling socket:close().
76 The optional timeout parameter may be used to wait until all data has been sent
77 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
78 happens first. A timeout value of 0 or nil causes immediate return and sending
79 of pending data in background (recommended).
82 ### socket:flush()
84 Alias for socket.output:flush()
87 ### socket.input
89 Lua file handle representing the input stream of the socket connection.
90 Supports the same methods as io.open()'s return values.
93 ### socket.interval
95 Set to the name of an interval timer if the "connect" handler was called due to
96 an elapsed interval timer. Otherwise nil.
99 ### socket:lines()
101 Alias for socket.input:lines()
104 ### socket.local_ip4
106 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
107 string.
110 ### socket.local_ip6
112 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
113 a string.
116 ### socket.local_tcpport
118 Local TCP port used for the connection.
121 ### socket.output
123 Lua file handle representing the output stream of the socket connection.
124 Supports the same methods as io.open()'s return values.
127 ### socket:read(...)
129 Alias for socket.input:read()
132 ### socket:readuntil(terminator, maxlen)
134 Reads as many bytes until a byte equal to the terminator value occurs. An
135 optional maximum length may be specified. The terminating byte is included in
136 the return value (unless the maximum length would be exceeded). On EOF, nil is
137 returned. In case of an I/O error, nil (as first result value) plus an error
138 message (as second result value) is returned.
140 This method is also available as :readuntil(...) for any other Lua file handle
141 (including socket.input).
144 ### socket.remote_ip4
146 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
147 a string.
150 ### socket.remote_ip6
152 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
153 a string.
156 ### socket.remote_tcpport
158 Remote TCP port used for the connection.
161 ### socket:write(...)
163 Alias for socket.output:write(...)
167 HTTP module
168 -----------
170 The http module exports the function http.generate_handler(callback) that
171 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
172 example of invocation. A table with options may be passed either as a second
173 argument, or as a first argument preceeding the callback function (whichever is
174 more convenient).
176 The following options are supported:
178 - request_body_size_limit: maximum size of payload of HTTP request body
179 (transfer encoding is allowed to add a limited amount of extra data)
180 - chunk_size: optional default value for maximum_input_chunk_size and
181 minimum_output_chunk_size
182 - request_header_size_limit: maximum size of HTTP request headers
183 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
184 certain POST fields (bigger chunks will be fragmented automatically)
185 - minimum_output_chunk_size: minimum size for a chunk when sending a response
186 body (smaller chunks will be buffered and concatenated with future data;
187 ignored when request:flush() is called)
188 - static_headers: a set of headers to be included in every HTTP response
189 (may be a string, a table or strings, or a table of key-value pairs)
191 The callback function receives a single request object as argument, which is
192 described below.
195 ### request.body
197 The request body (without headers) as a string. Accessing this value makes
198 further access to request.post_params and request.post_params_list, or
199 invocation of request:stream_request_body(...) impossible.
202 ### request:close_after_finish()
204 Closes the connection after answering the request.
206 This method can only be called before the HTTP response header section has been
207 finished (i.e. before request:finish_headers(), request:send_data(...), or
208 request:finish() were called), but it may be called before a status code has
209 been sent using request:send_status(...).
211 A corresponding "Connection: close" header is automatically sent.
214 ### request.cookies
216 A table with all cookies sent by the client.
219 ### request.defer_reading()
221 Disables automatic request body processing on write. Can be called before
222 sending a HTTP status code to send a response before the request has been fully
223 received.
225 CAUTION: Responding to a request before the request body has been processed may
226 lead to a deadlock if the browser does not process the response while trying to
227 send the request. Therefore, this function should only be used if:
229 - the TCP stack has enough buffer space for the response (i.e. if the response
230 is small enough), and if
231 - a timer is used to cancel the response in case of a deadlock.
233 It is recommended to not use this function unless certain performance tweaks
234 are desired.
237 ### request.faulty
239 Normally set to false. In case of a read or write error on the client
240 connection, this value is set to true before a Lua error is raised.
242 A faulty request handle must not be used, or another Lua error will be raised.
245 ### request:finish()
247 Finishes and flushes a HTTP response. May be called multiple times. An
248 HTTP status, all headers, and the response body (if applicable) must have been
249 previously sent. After calling this method, no further data may be written.
252 ### request:finish_headers()
254 Finishes and flushes the HTTP response header section. May be called multiple
255 times, as long as the request is not finished completely. This method is
256 automatically invoked if the application is beginning to send a response body.
257 After calling this method, no further headers may be sent.
260 ### request:flush()
262 Flushes any pending output data. Note: In order to mark the end of a response
263 body, it is required to call request:finish().
266 ### request.get_params
268 A table that maps field names to their corresponding GET value. If there are
269 several GET values with the given field name, then the first value is used.
271 Note: May be implemented through metamethods, but does support iteration
272 through pairs(...).
275 ### request.get_params_list
277 A table that maps field names to a sequence of their corresponding GET values.
279 Note: May be implemented through metamethods, but does support iteration
280 through pairs(...).
283 ### request.headers
285 A table that maps (case-insensitively) a HTTP header field name to a sequence
286 of values. One entry is created for every occurrence of a header line with the
287 given field name).
290 ### request.headers_csv_string
292 A table that maps (case-insensitively) a HTTP header field name to a comma
293 separated string. Multiple occurrences of the header with the given field name
294 are automatically merged into the comma separated string.
297 ### request.headers_csv_table
299 A table that maps (case-insensitively) a HTTP header field name to a sequence
300 of values. One entry is created for every comma separated value of each header
301 with the given field name.
304 ### request.headers_flags
306 A table that maps (case-insensitively) a HTTP header field name to another
307 table which (again case-insensitively) maps a string to a boolean, depending on
308 whether this string occurred in the list of comma separated values of one
309 header line with the given field name that was the key in the first table.
312 ### request.headers_value
314 A table that maps (case-insensitively) a HTTP header field name to a value. If
315 multiple header lines with the given field name have been received, false is
316 used as value.
319 ### request.method
321 The HTTP request method, e.g. "HEAD", "GET", or "POST".
324 ### request.path
326 The requested path without a leading slash and without the query part (e.g.
327 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
328 see request.query.
330 This value will be nil if (and only if) the request method is "OPTIONS" with a
331 request target equal to "*" (see also asterisk-form of request-target in
332 section 5.3.4 in RFC 7230).
335 ### request.post_metadata
337 Only set for multipart/form-data POST requests. A table that maps field names
338 to their corresponding POST metadata table which contains two entries:
339 "file_name" and "content_type". If there are several POST values with the given
340 field name, then the first value/file is used.
343 ### request.post_metadata_list
345 Only set for multipart/form-data POST requests. A table that maps field names
346 to a sequence with their corresponding POST metadata tables. Needed if multiple
347 files are uploaded with the same field name.
350 ### request.post_params
352 A table that maps field names to their corresponding POST value. If there are
353 several POST values with the given field name, then the first value is used.
355 Note: May be implemented through metamethods, but does support iteration
356 through pairs(...).
359 ### request.post_params_list
361 A table that maps field names to a sequence of their corresponding POST values.
363 Note: May be implemented through metamethods, but does support iteration
364 through pairs(...).
367 ### request.query
369 Query part of the request target including the leading question mark, e.g.
370 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
371 automatically parsed and made available through request.get_params and
372 request.get_params_list.
374 If there is no query part given in the request target, then this string is
375 the empty string. This value will be nil if (and only if) the request method
376 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
377 request-target in section 5.3.4 in RFC 7230).
380 ### request:process_request_body()
382 Starts processing the request body (if existent) to set the values
383 request.post_params, request.post_params_list, request.post_metadata, and
384 and request.post_metadata_list and/or to call POST field stream handlers that
385 have been previously registered with request:stream_post_param(...) or
386 request:stream_post_params(...).
388 This method gets invoked automatically when the POST param tables
389 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
390 deadlocks with the webbrowser). (Note: Automatic request body processing on
391 write may be disabled by calling request:defer_reading().)
393 After this method returned, all registered POST field stream handlers have
394 received all data. Registration of other POST field stream handlers is not
395 possible after this method has been called (or after request.post_params_list
396 or request.post_params have been accessed).
399 ### request:send_data(...)
401 Sends data as response body. All arguments are converted via tostring(...) and
402 concatenated. May be called multiple times until the request has been finished
403 by calling request:finish().
405 If the request method (see request.method) is "HEAD", then calls to
406 request:send_data(...) are automatically ignored.
409 ### request:send_header(key, value)
411 Sends a HTTP response header that consists of the given key and the given
412 value. Note: Key and value must be provided as separate arguments. Before any
413 headers can be sent, a HTTP status must have been set with
414 request:send_status(status_string).
417 ### request:send_status(status_string)
419 Sends a HTTP response status that is given as a string consisting of a 3-digit
420 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
421 function must be called once before any headers or response body data may be
422 sent.
425 ### request.socket
427 The underlaying socket. Can be used to force a TCP RST, etc.
430 ### request:stream_post_param(field_name, callback)
432 Registers a stream handler for the given POST parameter. The callback function
433 will be called in the following manner:
435 - For the initial chunk, the first chunk gets passed as first argument while a
436 table with metadata ("field_name" and "content_type") gets passed as second
437 argument. In case of an immediate EOF (i.e. an empty file), the passed
438 chunk is the empty string. In all other cases the chunk has a length greater
439 than zero.
440 - For any remaining chunks, the respective chunk gets passed as first and only
441 argument (no metadata). Here, the chunk has always a length greater than
442 zero.
443 - To indicate the end of the stream, the callback function is called without
444 arguments. This also happens in case of an immediate EOF (see above).
446 In case of an immediate EOF (i.e. an empty file), the callback function is thus
447 called as follows:
449 - The first time with an empty string as first argument, and with the metadata
450 as second argument.
451 - The second time without any arguments.
454 ### request:stream_post_params(pattern, callback)
456 Same as request:stream_post_param(...) but providing a string pattern to match
457 multiple field names (e.g. "^file_[0-9]+$").
460 ### request:stream_request_body(callback)
462 Start streaming of request body. For each chunk of the request body, the
463 callback function is called with the corresponding chunk. End of data is
464 indicated through return of request:stream_request_body(...) (not by calling
465 the callback without arguments).
467 The function may be called with nil instead of a callback function. In this
468 case, the request body is read and discarded. Only if nil is passed instead of
469 a callback, then the function may also be invoked when the request body has
470 already been read and/or processed. In the latter case, the function performs
471 no operation.

Impressum / About Us