| rev |
line source |
|
jbe@0
|
1
|
|
jbe@0
|
2 Moonbridge reference
|
|
jbe@0
|
3 ====================
|
|
jbe@0
|
4
|
|
jbe@0
|
5
|
|
jbe@0
|
6
|
|
jbe@52
|
7 Global function listen{...}
|
|
jbe@0
|
8 ---------------------------
|
|
jbe@0
|
9
|
|
jbe@0
|
10 This function initializes the Moonbridge Network Server. It may be called
|
|
jbe@0
|
11 multiple times. However, it is not allowed to register additional listeners by
|
|
jbe@0
|
12 calling listen(...) from a "prepare", "connect", or "finish" handler.
|
|
jbe@0
|
13
|
|
jbe@0
|
14 See file "example.lua" for parametrization of the listen(...) function.
|
|
jbe@0
|
15
|
|
jbe@0
|
16 Warning: Moonbridge will fork the Lua environment to handle parallel requests.
|
|
jbe@0
|
17 Functions provided as "prepare", "connect", and "finish" handlers may access
|
|
jbe@0
|
18 global variables, but for every child process these global variables will not
|
|
jbe@0
|
19 be shared! If you require a global state, a DBMS, cache server, or similar is
|
|
jbe@0
|
20 necessary.
|
|
jbe@0
|
21
|
|
jbe@0
|
22
|
|
jbe@0
|
23
|
|
jbe@50
|
24 Global function timeout(...)
|
|
jbe@50
|
25 ----------------------------
|
|
jbe@50
|
26
|
|
jbe@50
|
27 Calling this function with a positive number (time in seconds) sets a timer
|
|
jbe@50
|
28 that kills the current process after the selected time runs out. The remaining
|
|
jbe@50
|
29 time can be queried by calling this function without arguments.
|
|
jbe@50
|
30
|
|
jbe@50
|
31 Calling this function with a single argument that is the number zero will
|
|
jbe@50
|
32 disable the timeout.
|
|
jbe@50
|
33
|
|
jbe@50
|
34 Another mode of operation is selected by passing two arguments: a time (in
|
|
jbe@50
|
35 seconds) as first argument and a function as second argument. In this case, a
|
|
jbe@50
|
36 sub-timer will be used to limit the execution time of the function. In case of
|
|
jbe@50
|
37 timeout, the process will be killed (and the timeout function does not return).
|
|
jbe@50
|
38 If the time for the sub-timer is longer than a previously set timeout (using
|
|
jbe@50
|
39 the timeout(...) function with one argument), the shorter timeout (of the
|
|
jbe@50
|
40 previous call of timeout(...)) will have precedence.
|
|
jbe@50
|
41
|
|
jbe@52
|
42 Timers are also automatically reset (disabled) when a handler (prepare handler
|
|
jbe@52
|
43 or connect handler) returns. To shutdown processes after a certain time waiting
|
|
jbe@52
|
44 for a new request, use the idle_time parameter of the listen function.
|
|
jbe@52
|
45
|
|
jbe@50
|
46
|
|
jbe@50
|
47
|
|
jbe@0
|
48 Socket object passed to "connect" handler
|
|
jbe@0
|
49 -----------------------------------------
|
|
jbe@0
|
50
|
|
jbe@0
|
51 For every incoming connection, the registered "connect" handler is called with
|
|
jbe@0
|
52 a single socket object as argument, which is described below:
|
|
jbe@0
|
53
|
|
jbe@0
|
54
|
|
jbe@94
|
55 ### socket:close()
|
|
jbe@0
|
56
|
|
jbe@0
|
57 Closes the socket connection (input and output stream) by flushing all data and
|
|
jbe@94
|
58 sending a TCP FIN packet.
|
|
jbe@91
|
59
|
|
jbe@91
|
60 Returns true on success, or nil plus error message in case of an I/O error.
|
|
jbe@91
|
61 Using this method on sockets that have already been closed (or reset) will
|
|
jbe@91
|
62 throw an error.
|
|
jbe@0
|
63
|
|
jbe@0
|
64 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
|
|
jbe@94
|
65 when network connections are used. All pending input data should have been read
|
|
jbe@94
|
66 (or drained) before calling socket:close(). Use socket:finish() to send a
|
|
jbe@94
|
67 TCP FIN packet to the peer before waiting for EOF from the peer.
|
|
jbe@91
|
68
|
|
jbe@91
|
69
|
|
jbe@91
|
70 ### socket:drain(maxlen, terminator)
|
|
jbe@0
|
71
|
|
jbe@91
|
72 Same as socket:read(maxlen, terminator), but discards the input and returns the
|
|
jbe@143
|
73 number of discarded bytes (as first return value) and the status code ("term",
|
|
jbe@143
|
74 "maxlen", "eof" as second return value).
|
|
jbe@91
|
75
|
|
jbe@91
|
76 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
77 second return value) are returned.
|
|
jbe@0
|
78
|
|
jbe@0
|
79
|
|
jbe@144
|
80 ### socket:drain_call(waitfunc, maxlen, terminator)
|
|
jbe@144
|
81
|
|
jbe@144
|
82 Same as socket:drain(maxlen, terminator), but calls waitfunc(socket, "r") (in
|
|
jbe@144
|
83 an infinite loop) as long as the reading is blocked.
|
|
jbe@144
|
84
|
|
jbe@144
|
85
|
|
jbe@91
|
86 ### socket:drain_nb(maxlen, terminator)
|
|
jbe@0
|
87
|
|
jbe@143
|
88 Same as socket:drain(maxlen, terminator), but non-blocking. The status code
|
|
jbe@143
|
89 (which is returned as second return value) may therefore be "term", "maxlen",
|
|
jbe@143
|
90 "eof", or "block".
|
|
jbe@91
|
91
|
|
jbe@91
|
92 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
93 second return value) are returned.
|
|
jbe@91
|
94
|
|
jbe@0
|
95
|
|
jbe@144
|
96 ### socket:drain_yield(maxlen, terminator)
|
|
jbe@144
|
97
|
|
jbe@144
|
98 Alias for socket:drain_call(coroutine.yield, maxlen, terminator)
|
|
jbe@144
|
99
|
|
jbe@144
|
100
|
|
jbe@94
|
101 ### socket:finish()
|
|
jbe@94
|
102
|
|
jbe@94
|
103 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
|
|
jbe@94
|
104 still possible. When there is no more input data to be read, the connection
|
|
jbe@94
|
105 should finally be closed with socket:close().
|
|
jbe@94
|
106
|
|
jbe@94
|
107 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
|
|
jbe@94
|
108 the underlying socket and emulates EOF on subsequent reads. Also in this case,
|
|
jbe@94
|
109 the connection should be finally closed with socket:close().
|
|
jbe@94
|
110
|
|
jbe@94
|
111
|
|
jbe@91
|
112 ### socket:flush(...)
|
|
jbe@91
|
113
|
|
jbe@91
|
114 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
|
|
jbe@91
|
115 data is passed to the operating system).
|
|
jbe@91
|
116
|
|
jbe@91
|
117 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
118 second return value) are returned. On success, the socket userdata object is
|
|
jbe@91
|
119 returned.
|
|
jbe@91
|
120
|
|
jbe@0
|
121
|
|
jbe@145
|
122 ### socket:flush_call(waitfunc, ...)
|
|
jbe@145
|
123
|
|
jbe@145
|
124 Same as socket:flush(...), but calls waitfunc(socket, "w") (in an infinite
|
|
jbe@145
|
125 loop) as long as the writing is blocked.
|
|
jbe@145
|
126
|
|
jbe@145
|
127
|
|
jbe@91
|
128 ### socket:flush_nb(...)
|
|
jbe@91
|
129
|
|
jbe@91
|
130 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
|
|
jbe@91
|
131 pending data is passed to the operating system). The total number of bytes that
|
|
jbe@91
|
132 could not be passed yet to the operating system is returned. Zero is returned
|
|
jbe@91
|
133 if all data could be flushed out.
|
|
jbe@91
|
134
|
|
jbe@91
|
135 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
136 second return value) are returned.
|
|
jbe@0
|
137
|
|
jbe@0
|
138
|
|
jbe@145
|
139 ### socket:flush_yield(...)
|
|
jbe@145
|
140
|
|
jbe@145
|
141 Alias for socket:flush_call(coroutine.yield, ...)
|
|
jbe@145
|
142
|
|
jbe@145
|
143
|
|
jbe@0
|
144 ### socket.interval
|
|
jbe@0
|
145
|
|
jbe@0
|
146 Set to the name of an interval timer if the "connect" handler was called due to
|
|
jbe@0
|
147 an elapsed interval timer. Otherwise nil.
|
|
jbe@0
|
148
|
|
jbe@0
|
149
|
|
jbe@0
|
150 ### socket.local_ip4
|
|
jbe@0
|
151
|
|
jbe@0
|
152 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
|
|
jbe@0
|
153 string.
|
|
jbe@0
|
154
|
|
jbe@0
|
155
|
|
jbe@0
|
156 ### socket.local_ip6
|
|
jbe@0
|
157
|
|
jbe@0
|
158 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
|
|
jbe@0
|
159 a string.
|
|
jbe@0
|
160
|
|
jbe@0
|
161
|
|
jbe@0
|
162 ### socket.local_tcpport
|
|
jbe@0
|
163
|
|
jbe@0
|
164 Local TCP port used for the connection.
|
|
jbe@0
|
165
|
|
jbe@0
|
166
|
|
jbe@91
|
167 ### socket:read(maxlen, terminator)
|
|
jbe@0
|
168
|
|
jbe@143
|
169 Reads up to maxlen bytes or until an optional termination character is
|
|
jbe@91
|
170 encountered (which is included in the result). The maxlen value may be nil, in
|
|
jbe@91
|
171 which case there is no limit on the number of bytes read.
|
|
jbe@0
|
172
|
|
jbe@91
|
173 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
174 second return value) are returned.
|
|
jbe@0
|
175
|
|
jbe@143
|
176 In all other cases (including EOF), the following two values are returned:
|
|
jbe@143
|
177
|
|
jbe@143
|
178 - a string containing the bytes read (first return value, may be empty string)
|
|
jbe@143
|
179 - a status code equal to "term", "maxlen", or "eof" (second return value)
|
|
jbe@143
|
180
|
|
jbe@143
|
181 If an EOF is encountered before all data could be read, then "eof" is returned
|
|
jbe@143
|
182 as second return value. If maxlen bytes have been read and no termination
|
|
jbe@143
|
183 character has been read, then "maxlen" is returned as second return value. If
|
|
jbe@143
|
184 the termination character is the last character of the read string, the second
|
|
jbe@143
|
185 return value will be "term".
|
|
jbe@143
|
186
|
|
jbe@0
|
187
|
|
jbe@140
|
188 ### socket:read_call(waitfunc, maxlen, terminator)
|
|
jbe@140
|
189
|
|
jbe@149
|
190 Same as socket:read(maxlen, terminator), but calls waitfunc(
|
|
jbe@149
|
191 moonbridge_io.block, socket, "r") (in an infinite loop) as long as the reading
|
|
jbe@149
|
192 is blocked.
|
|
jbe@140
|
193
|
|
jbe@140
|
194
|
|
jbe@91
|
195 ### socket:read_nb(maxlen, terminator)
|
|
jbe@91
|
196
|
|
jbe@143
|
197 Same as socket:read(maxlen, terminator), but does not block.
|
|
jbe@91
|
198
|
|
jbe@91
|
199 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
200 second return value) are returned.
|
|
jbe@78
|
201
|
|
jbe@143
|
202 In all other cases (including EOF), the following two values are returned:
|
|
jbe@143
|
203
|
|
jbe@143
|
204 - a string containing the bytes read (first return value, may be empty string)
|
|
jbe@143
|
205 - a status code equal to "term", "maxlen", "eof", "block" (second return value)
|
|
jbe@143
|
206
|
|
jbe@143
|
207 The status code "block" as second return value is used if the function returned
|
|
jbe@143
|
208 prematurely because it would block otherwise. In this case, the first return
|
|
jbe@143
|
209 value is a string that contains the bytes that could be read without blocking.
|
|
jbe@143
|
210
|
|
jbe@78
|
211
|
|
jbe@140
|
212 ### socket:read_yield(maxlen, terminator)
|
|
jbe@140
|
213
|
|
jbe@140
|
214 Alias for socket:read_call(coroutine.yield, maxlen, terminator)
|
|
jbe@140
|
215
|
|
jbe@140
|
216
|
|
jbe@0
|
217 ### socket.remote_ip4
|
|
jbe@0
|
218
|
|
jbe@0
|
219 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
|
|
jbe@0
|
220 a string.
|
|
jbe@0
|
221
|
|
jbe@0
|
222
|
|
jbe@0
|
223 ### socket.remote_ip6
|
|
jbe@0
|
224
|
|
jbe@0
|
225 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
|
|
jbe@0
|
226 a string.
|
|
jbe@0
|
227
|
|
jbe@0
|
228
|
|
jbe@0
|
229 ### socket.remote_tcpport
|
|
jbe@0
|
230
|
|
jbe@0
|
231 Remote TCP port used for the connection.
|
|
jbe@0
|
232
|
|
jbe@0
|
233
|
|
jbe@91
|
234 ### socket:reset()
|
|
jbe@91
|
235
|
|
jbe@91
|
236 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
|
|
jbe@91
|
237 packet if possible to indicate error condition.
|
|
jbe@91
|
238
|
|
jbe@114
|
239 Returns true on success, or nil (as first return value) plus error message (as
|
|
jbe@114
|
240 second return value) in case of an I/O error. Using this method on sockets that
|
|
jbe@91
|
241 have already been closed (or reset) will throw an error.
|
|
jbe@91
|
242
|
|
jbe@91
|
243 Warning: Previously sent (and flushed) data may be lost during transmission.
|
|
jbe@91
|
244
|
|
jbe@91
|
245
|
|
jbe@0
|
246 ### socket:write(...)
|
|
jbe@0
|
247
|
|
jbe@91
|
248 Takes a variable number of strings and sends them to the peer. The operation is
|
|
jbe@91
|
249 buffered, so to actually send out the data, it is necessary to eventually call
|
|
jbe@91
|
250 socket:flush(), socket:finish(), or socket:close().
|
|
jbe@91
|
251
|
|
jbe@91
|
252 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
253 second return value) are returned. On success, the socket userdata object is
|
|
jbe@91
|
254 returned.
|
|
jbe@91
|
255
|
|
jbe@91
|
256
|
|
jbe@145
|
257 ### socket:write_call(waitfunc, ...)
|
|
jbe@145
|
258
|
|
jbe@149
|
259 Same as socket:write(...), but calls waitfunc(moonbridge_io.block, socket,
|
|
jbe@149
|
260 "w") (in an infinite loop) as long as the writing is blocked.
|
|
jbe@145
|
261
|
|
jbe@145
|
262
|
|
jbe@91
|
263 ### socket:write_nb(...)
|
|
jbe@91
|
264
|
|
jbe@91
|
265 Takes a variable number of strings and sends them to the peer. The operation is
|
|
jbe@91
|
266 buffered, so to actually send out the data, it is necessary to eventually call
|
|
jbe@91
|
267 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
|
|
jbe@91
|
268
|
|
jbe@91
|
269 This function always returns immediately (i.e. it does not block). If all data
|
|
jbe@91
|
270 (but a small buffered portion) could be sent out, then zero is returned.
|
|
jbe@91
|
271 Otherwise, all arguments that could not be sent are stored in a buffer of
|
|
jbe@91
|
272 unlimited size (up to memory capabilities) and an integer is returned that
|
|
jbe@91
|
273 indicates the number of bytes currently in the buffer.
|
|
jbe@91
|
274
|
|
jbe@91
|
275 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
276 second return value) are returned.
|
|
jbe@0
|
277
|
|
jbe@0
|
278
|
|
jbe@145
|
279 ### socket:write_yield(...)
|
|
jbe@145
|
280
|
|
jbe@145
|
281 Alias for socket:write_call(coroutine.yield, ...)
|
|
jbe@145
|
282
|
|
jbe@145
|
283
|
|
jbe@0
|
284
|
|
jbe@98
|
285 I/O library
|
|
jbe@98
|
286 -----------
|
|
jbe@98
|
287
|
|
jbe@98
|
288 The Moonbridge Network Server for Lua Applications comes with its own I/O
|
|
jbe@98
|
289 library to support blocking as well as nonblocking I/O operations.
|
|
jbe@98
|
290
|
|
jbe@114
|
291 All methods on an I/O handle (e.g. socket) are described in the previous
|
|
jbe@114
|
292 section regarding the "socket" object. All other functions of the library are
|
|
jbe@114
|
293 listed below.
|
|
jbe@114
|
294
|
|
jbe@114
|
295
|
|
jbe@149
|
296 ### moonbridge_io.block
|
|
jbe@149
|
297
|
|
jbe@149
|
298 An opaque value (lightuserdata) used by yielding non-blocking I/O functions.
|
|
jbe@149
|
299
|
|
jbe@149
|
300 When socket:read_yield(...) could not read from a socket, it yields the three
|
|
jbe@149
|
301 values moonbridge_io.block, the socket, and the string "r".
|
|
jbe@149
|
302 When socket:write_yield(...) could not write to a socket, it yields the three
|
|
jbe@149
|
303 values moonbridge_io.block, the socket, and the string "w".
|
|
jbe@149
|
304
|
|
jbe@149
|
305 See reference for moonbridge_io.run(...) for further information.
|
|
jbe@149
|
306
|
|
jbe@149
|
307
|
|
jbe@114
|
308 ### moonbridge_io.localconnect(path)
|
|
jbe@114
|
309
|
|
jbe@114
|
310 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
|
|
jbe@114
|
311 a socket object on success, or nil (as first return value) plus an error
|
|
jbe@114
|
312 message (as second return value) in case of error.
|
|
jbe@114
|
313
|
|
jbe@114
|
314
|
|
jbe@114
|
315 ### moonbridge_io.localconnect_nb(path)
|
|
jbe@114
|
316
|
|
jbe@114
|
317 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
|
|
jbe@114
|
318 a socket object on success, or nil (as first return value) plus an error
|
|
jbe@114
|
319 message (as second return value) in case of error.
|
|
jbe@114
|
320
|
|
jbe@114
|
321 Same as moonbridge_io.localconnect(path), except that this function does not
|
|
jbe@114
|
322 block and immediately returns a socket object.
|
|
jbe@114
|
323
|
|
jbe@114
|
324 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
325 second return value) may be returned. However, connection errors may also be
|
|
jbe@114
|
326 reported on first read or write on the socket.
|
|
jbe@114
|
327
|
|
jbe@114
|
328
|
|
jbe@114
|
329 ### moonbridge_io.locallisten(path)
|
|
jbe@114
|
330
|
|
jbe@114
|
331 Attempts to create a local socket (also known as Unix Domain Socket) to accept
|
|
jbe@118
|
332 incoming connections. If the file does already exist and is a socket, then it
|
|
jbe@118
|
333 is deleted automatically before being re-created.
|
|
jbe@114
|
334
|
|
jbe@114
|
335 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
336 second return value) may be returned.On success, a listener object is returned
|
|
jbe@114
|
337 which supports the methods :accept(), :accept_nb(), and :close().
|
|
jbe@114
|
338
|
|
jbe@114
|
339 The method :accept() blocks until a new incoming connection is available in
|
|
jbe@114
|
340 which case a socket object is returned.
|
|
jbe@114
|
341
|
|
jbe@114
|
342 The method :accept_nb() works like :accept(), except that the call is
|
|
jbe@114
|
343 nonblocking and returns false (plus a notice as second return value) in case no
|
|
jbe@114
|
344 incoming connection is available. It is possible to wait for an incoming
|
|
jbe@114
|
345 connection by including the listener object in the input_set of the
|
|
jbe@114
|
346 moonbridge_io.poll(...) call.
|
|
jbe@114
|
347
|
|
jbe@114
|
348 The method :close() will close the listening socket. In case of local sockets
|
|
jbe@114
|
349 (Unix Domain Sockets), the socket will not be unlinked in the file system.
|
|
jbe@114
|
350
|
|
jbe@114
|
351 I/O errors by the methods of the listener object are also reported by returning
|
|
jbe@114
|
352 nil (as first return value) plus an error message (as second return value).
|
|
jbe@114
|
353
|
|
jbe@98
|
354
|
|
jbe@149
|
355 ### moonbridge_io.multiblock
|
|
jbe@149
|
356
|
|
jbe@149
|
357 An opaque value (lightuserdata) used by yielding non-blocking I/O functions.
|
|
jbe@149
|
358 See reference for moonbridge_io.run(...) for further information.
|
|
jbe@149
|
359
|
|
jbe@149
|
360
|
|
jbe@106
|
361 ### moonbridge_io.poll(input_set, output_set, timeout)
|
|
jbe@106
|
362
|
|
jbe@106
|
363 This function waits for at least one of the given file descriptors and/or
|
|
jbe@106
|
364 I/O handles to be ready for input or output. The two sets of file descriptors
|
|
jbe@106
|
365 and/or handles must contain the file descriptor or handle as a key, and a value
|
|
jbe@106
|
366 which does evaluate to true. If a set is nil, it is treated as being empty.
|
|
jbe@106
|
367
|
|
jbe@106
|
368 Returns true when at least one file descriptor or handle is ready for reading
|
|
jbe@106
|
369 or writing respectively. Returns false (as first return value) plus a status
|
|
jbe@106
|
370 message (as second return value) in case of timeout or when a signal was
|
|
jbe@106
|
371 received.
|
|
jbe@106
|
372
|
|
jbe@106
|
373
|
|
jbe@149
|
374 ### moonbridge_io.run(function_set, timeout_or_poll_func)
|
|
jbe@149
|
375
|
|
jbe@149
|
376 Executes multiple coroutines (created via coroutine.wrap(...)) in the following
|
|
jbe@149
|
377 way:
|
|
jbe@149
|
378
|
|
jbe@149
|
379 function moonbridge_io.run(function_set, timeout_or_poll_func)
|
|
jbe@149
|
380 local pairs = function(t) return next, t end -- raw pairs
|
|
jbe@149
|
381 local starttime = moonbridge_io.timeref()
|
|
jbe@149
|
382 local read_fds, write_fds = {}, {}
|
|
jbe@149
|
383 while true do
|
|
jbe@149
|
384 local work_to_do = false
|
|
jbe@149
|
385 for func, result_handler in pairs(function_set) do
|
|
jbe@149
|
386 ::again::
|
|
jbe@151
|
387 local res = table.pack(func())
|
|
jbe@151
|
388 if res[1] == moonbridge_io.block then
|
|
jbe@151
|
389 if string.match(res[3], "r") then
|
|
jbe@151
|
390 read_fds[res[2]] = true
|
|
jbe@149
|
391 end
|
|
jbe@151
|
392 if string.match(res[3], "w") then
|
|
jbe@151
|
393 write_fds[res[2]] = true
|
|
jbe@149
|
394 end
|
|
jbe@149
|
395 work_to_do = true
|
|
jbe@151
|
396 elseif res[1] == moonbridge_io.multiblock then
|
|
jbe@151
|
397 for fd, active in pairs(res[2]) do
|
|
jbe@149
|
398 if active then read_fds[fd] = true end
|
|
jbe@149
|
399 end
|
|
jbe@151
|
400 for fd, active in pairs(res[3]) do
|
|
jbe@149
|
401 if active then write_fds[fd] = true end
|
|
jbe@149
|
402 end
|
|
jbe@149
|
403 work_to_do = true
|
|
jbe@149
|
404 else
|
|
jbe@151
|
405 if
|
|
jbe@151
|
406 result_handler == true or
|
|
jbe@151
|
407 result_handler(table.unpack(res, 1, res.n))
|
|
jbe@151
|
408 then
|
|
jbe@151
|
409 function_set[func] = nil -- task finished
|
|
jbe@149
|
410 else
|
|
jbe@149
|
411 goto again
|
|
jbe@149
|
412 end
|
|
jbe@149
|
413 end
|
|
jbe@149
|
414 end
|
|
jbe@149
|
415 if not work_to_do then
|
|
jbe@149
|
416 return true -- all tasks finished
|
|
jbe@149
|
417 end
|
|
jbe@149
|
418 if type(timeout_or_poll_func) == "function" then
|
|
jbe@149
|
419 local poll_func = timeout_or_poll_func
|
|
jbe@149
|
420 if
|
|
jbe@149
|
421 poll_func(moonbridge_io.multiblock, read_fds, write_fds) == false
|
|
jbe@149
|
422 then
|
|
jbe@149
|
423 return false
|
|
jbe@149
|
424 end
|
|
jbe@149
|
425 elseif type(timeout_or_poll_func) == "number" then
|
|
jbe@149
|
426 local timeout = timeout_or_poll_func
|
|
jbe@149
|
427 if
|
|
jbe@149
|
428 moonbridge_io.poll(
|
|
jbe@149
|
429 read_fds,
|
|
jbe@149
|
430 write_fds,
|
|
jbe@150
|
431 timeout - moonbridge_io.timeref(starttime)
|
|
jbe@149
|
432 ) == false
|
|
jbe@149
|
433 then
|
|
jbe@149
|
434 return false -- timeout
|
|
jbe@149
|
435 end
|
|
jbe@149
|
436 else
|
|
jbe@149
|
437 moonbridge_io.poll(read_fds, write_fds)
|
|
jbe@149
|
438 end
|
|
jbe@149
|
439 for fd in pairs(read_fds) do read_fds[fd] = nil end
|
|
jbe@149
|
440 for fd in pairs(write_fds) do write_fds[fd] = nil end
|
|
jbe@149
|
441 end
|
|
jbe@149
|
442 end
|
|
jbe@149
|
443
|
|
jbe@149
|
444
|
|
jbe@98
|
445 ### moonbridge_io.tcpconnect(hostname, port)
|
|
jbe@98
|
446
|
|
jbe@98
|
447 Tries to open a TCP connection with the given host and TCP port number. Returns
|
|
jbe@114
|
448 a socket object on success, or nil (as first return value) plus an error
|
|
jbe@114
|
449 message (as second return value) in case of error.
|
|
jbe@98
|
450
|
|
jbe@98
|
451
|
|
jbe@99
|
452 ### moonbridge_io.tcpconnect_nb(hostname, port)
|
|
jbe@99
|
453
|
|
jbe@99
|
454 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
|
|
jbe@99
|
455 does not block and immediately returns a socket object.
|
|
jbe@99
|
456
|
|
jbe@102
|
457 Note: The current implementation still blocks during the DNS lookup. Use a
|
|
jbe@102
|
458 numeric IP address as hostname to be truly nonblocking.
|
|
jbe@102
|
459
|
|
jbe@99
|
460 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
461 second return value) may be returned. However, connection errors may also be
|
|
jbe@99
|
462 reported on first read or write on the socket.
|
|
jbe@99
|
463
|
|
jbe@99
|
464
|
|
jbe@114
|
465 ### moonbridge_io.tcplisten(hostname, port)
|
|
jbe@114
|
466
|
|
jbe@114
|
467 Attempts to open a TCP port for listening. To listen on the loopback interface,
|
|
jbe@114
|
468 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
|
|
jbe@114
|
469 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
|
|
jbe@114
|
470 "0.0.0.0" (IPv4) respectively.
|
|
jbe@114
|
471
|
|
jbe@114
|
472 In case of an I/O error, nil (as first return value) plus an error message (as
|
|
jbe@114
|
473 second return value) may be returned. On success, a listener object is returned
|
|
jbe@114
|
474 which supports the methods :accept(), :accept_nb(), and :close(). See reference
|
|
jbe@114
|
475 for moonbridge.io_locallisten(...).
|
|
jbe@114
|
476
|
|
jbe@114
|
477
|
|
jbe@98
|
478
|
|
jbe@0
|
479 HTTP module
|
|
jbe@0
|
480 -----------
|
|
jbe@0
|
481
|
|
jbe@0
|
482 The http module exports the function http.generate_handler(callback) that
|
|
jbe@0
|
483 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
|
|
jbe@0
|
484 example of invocation. A table with options may be passed either as a second
|
|
jbe@0
|
485 argument, or as a first argument preceeding the callback function (whichever is
|
|
jbe@0
|
486 more convenient).
|
|
jbe@0
|
487
|
|
jbe@0
|
488 The following options are supported:
|
|
jbe@0
|
489
|
|
jbe@0
|
490 - request_body_size_limit: maximum size of payload of HTTP request body
|
|
jbe@0
|
491 (transfer encoding is allowed to add a limited amount of extra data)
|
|
jbe@0
|
492 - chunk_size: optional default value for maximum_input_chunk_size and
|
|
jbe@0
|
493 minimum_output_chunk_size
|
|
jbe@0
|
494 - request_header_size_limit: maximum size of HTTP request headers
|
|
jbe@0
|
495 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
|
|
jbe@0
|
496 certain POST fields (bigger chunks will be fragmented automatically)
|
|
jbe@0
|
497 - minimum_output_chunk_size: minimum size for a chunk when sending a response
|
|
jbe@0
|
498 body (smaller chunks will be buffered and concatenated with future data;
|
|
jbe@0
|
499 ignored when request:flush() is called)
|
|
jbe@0
|
500 - static_headers: a set of headers to be included in every HTTP response
|
|
jbe@0
|
501 (may be a string, a table or strings, or a table of key-value pairs)
|
|
jbe@0
|
502
|
|
jbe@0
|
503 The callback function receives a single request object as argument, which is
|
|
jbe@0
|
504 described below.
|
|
jbe@0
|
505
|
|
jbe@0
|
506
|
|
jbe@0
|
507 ### request.body
|
|
jbe@0
|
508
|
|
jbe@0
|
509 The request body (without headers) as a string. Accessing this value makes
|
|
jbe@0
|
510 further access to request.post_params and request.post_params_list, or
|
|
jbe@0
|
511 invocation of request:stream_request_body(...) impossible.
|
|
jbe@0
|
512
|
|
jbe@0
|
513
|
|
jbe@60
|
514 ### request:close_after_finish()
|
|
jbe@60
|
515
|
|
jbe@60
|
516 Closes the connection after answering the request.
|
|
jbe@60
|
517
|
|
jbe@60
|
518 This method can only be called before the HTTP response header section has been
|
|
jbe@60
|
519 finished (i.e. before request:finish_headers(), request:send_data(...), or
|
|
jbe@60
|
520 request:finish() were called), but it may be called before a status code has
|
|
jbe@60
|
521 been sent using request:send_status(...).
|
|
jbe@60
|
522
|
|
jbe@60
|
523 A corresponding "Connection: close" header is automatically sent.
|
|
jbe@60
|
524
|
|
jbe@60
|
525
|
|
jbe@0
|
526 ### request.cookies
|
|
jbe@0
|
527
|
|
jbe@0
|
528 A table with all cookies sent by the client.
|
|
jbe@0
|
529
|
|
jbe@0
|
530
|
|
jbe@0
|
531 ### request.defer_reading()
|
|
jbe@0
|
532
|
|
jbe@0
|
533 Disables automatic request body processing on write. Can be called before
|
|
jbe@0
|
534 sending a HTTP status code to send a response before the request has been fully
|
|
jbe@0
|
535 received.
|
|
jbe@0
|
536
|
|
jbe@0
|
537 CAUTION: Responding to a request before the request body has been processed may
|
|
jbe@0
|
538 lead to a deadlock if the browser does not process the response while trying to
|
|
jbe@0
|
539 send the request. Therefore, this function should only be used if:
|
|
jbe@0
|
540
|
|
jbe@0
|
541 - the TCP stack has enough buffer space for the response (i.e. if the response
|
|
jbe@0
|
542 is small enough), and if
|
|
jbe@0
|
543 - a timer is used to cancel the response in case of a deadlock.
|
|
jbe@0
|
544
|
|
jbe@0
|
545 It is recommended to not use this function unless certain performance tweaks
|
|
jbe@0
|
546 are desired.
|
|
jbe@0
|
547
|
|
jbe@0
|
548
|
|
jbe@50
|
549 ### request.faulty
|
|
jbe@50
|
550
|
|
jbe@50
|
551 Normally set to false. In case of a read or write error on the client
|
|
jbe@50
|
552 connection, this value is set to true before a Lua error is raised.
|
|
jbe@50
|
553
|
|
jbe@50
|
554 A faulty request handle must not be used, or another Lua error will be raised.
|
|
jbe@50
|
555
|
|
jbe@50
|
556
|
|
jbe@0
|
557 ### request:finish()
|
|
jbe@0
|
558
|
|
jbe@0
|
559 Finishes and flushes a HTTP response. May be called multiple times. An
|
|
jbe@0
|
560 HTTP status, all headers, and the response body (if applicable) must have been
|
|
jbe@0
|
561 previously sent. After calling this method, no further data may be written.
|
|
jbe@0
|
562
|
|
jbe@0
|
563
|
|
jbe@0
|
564 ### request:finish_headers()
|
|
jbe@0
|
565
|
|
jbe@0
|
566 Finishes and flushes the HTTP response header section. May be called multiple
|
|
jbe@0
|
567 times, as long as the request is not finished completely. This method is
|
|
jbe@0
|
568 automatically invoked if the application is beginning to send a response body.
|
|
jbe@0
|
569 After calling this method, no further headers may be sent.
|
|
jbe@0
|
570
|
|
jbe@0
|
571
|
|
jbe@0
|
572 ### request:flush()
|
|
jbe@0
|
573
|
|
jbe@0
|
574 Flushes any pending output data. Note: In order to mark the end of a response
|
|
jbe@0
|
575 body, it is required to call request:finish().
|
|
jbe@0
|
576
|
|
jbe@0
|
577
|
|
jbe@0
|
578 ### request.get_params
|
|
jbe@0
|
579
|
|
jbe@0
|
580 A table that maps field names to their corresponding GET value. If there are
|
|
jbe@0
|
581 several GET values with the given field name, then the first value is used.
|
|
jbe@0
|
582
|
|
jbe@35
|
583 Note: May be implemented through metamethods, but does support iteration
|
|
jbe@35
|
584 through pairs(...).
|
|
jbe@35
|
585
|
|
jbe@0
|
586
|
|
jbe@0
|
587 ### request.get_params_list
|
|
jbe@0
|
588
|
|
jbe@0
|
589 A table that maps field names to a sequence of their corresponding GET values.
|
|
jbe@0
|
590
|
|
jbe@35
|
591 Note: May be implemented through metamethods, but does support iteration
|
|
jbe@35
|
592 through pairs(...).
|
|
jbe@35
|
593
|
|
jbe@0
|
594
|
|
jbe@0
|
595 ### request.headers
|
|
jbe@0
|
596
|
|
jbe@0
|
597 A table that maps (case-insensitively) a HTTP header field name to a sequence
|
|
jbe@0
|
598 of values. One entry is created for every occurrence of a header line with the
|
|
jbe@0
|
599 given field name).
|
|
jbe@0
|
600
|
|
jbe@0
|
601
|
|
jbe@0
|
602 ### request.headers_csv_string
|
|
jbe@0
|
603
|
|
jbe@0
|
604 A table that maps (case-insensitively) a HTTP header field name to a comma
|
|
jbe@0
|
605 separated string. Multiple occurrences of the header with the given field name
|
|
jbe@0
|
606 are automatically merged into the comma separated string.
|
|
jbe@0
|
607
|
|
jbe@0
|
608
|
|
jbe@0
|
609 ### request.headers_csv_table
|
|
jbe@0
|
610
|
|
jbe@0
|
611 A table that maps (case-insensitively) a HTTP header field name to a sequence
|
|
jbe@0
|
612 of values. One entry is created for every comma separated value of each header
|
|
jbe@0
|
613 with the given field name.
|
|
jbe@0
|
614
|
|
jbe@0
|
615
|
|
jbe@0
|
616 ### request.headers_flags
|
|
jbe@0
|
617
|
|
jbe@0
|
618 A table that maps (case-insensitively) a HTTP header field name to another
|
|
jbe@0
|
619 table which (again case-insensitively) maps a string to a boolean, depending on
|
|
jbe@0
|
620 whether this string occurred in the list of comma separated values of one
|
|
jbe@0
|
621 header line with the given field name that was the key in the first table.
|
|
jbe@0
|
622
|
|
jbe@0
|
623
|
|
jbe@0
|
624 ### request.headers_value
|
|
jbe@0
|
625
|
|
jbe@0
|
626 A table that maps (case-insensitively) a HTTP header field name to a value. If
|
|
jbe@0
|
627 multiple header lines with the given field name have been received, false is
|
|
jbe@0
|
628 used as value.
|
|
jbe@0
|
629
|
|
jbe@0
|
630
|
|
jbe@0
|
631 ### request.method
|
|
jbe@0
|
632
|
|
jbe@0
|
633 The HTTP request method, e.g. "HEAD", "GET", or "POST".
|
|
jbe@0
|
634
|
|
jbe@0
|
635
|
|
jbe@0
|
636 ### request.path
|
|
jbe@0
|
637
|
|
jbe@10
|
638 The requested path without a leading slash and without the query part (e.g.
|
|
jbe@10
|
639 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
|
|
jbe@10
|
640 see request.query.
|
|
jbe@10
|
641
|
|
jbe@10
|
642 This value will be nil if (and only if) the request method is "OPTIONS" with a
|
|
jbe@10
|
643 request target equal to "*" (see also asterisk-form of request-target in
|
|
jbe@10
|
644 section 5.3.4 in RFC 7230).
|
|
jbe@0
|
645
|
|
jbe@0
|
646
|
|
jbe@0
|
647 ### request.post_metadata
|
|
jbe@0
|
648
|
|
jbe@0
|
649 Only set for multipart/form-data POST requests. A table that maps field names
|
|
jbe@0
|
650 to their corresponding POST metadata table which contains two entries:
|
|
jbe@0
|
651 "file_name" and "content_type". If there are several POST values with the given
|
|
jbe@0
|
652 field name, then the first value/file is used.
|
|
jbe@0
|
653
|
|
jbe@0
|
654
|
|
jbe@0
|
655 ### request.post_metadata_list
|
|
jbe@0
|
656
|
|
jbe@0
|
657 Only set for multipart/form-data POST requests. A table that maps field names
|
|
jbe@0
|
658 to a sequence with their corresponding POST metadata tables. Needed if multiple
|
|
jbe@0
|
659 files are uploaded with the same field name.
|
|
jbe@0
|
660
|
|
jbe@0
|
661
|
|
jbe@0
|
662 ### request.post_params
|
|
jbe@0
|
663
|
|
jbe@0
|
664 A table that maps field names to their corresponding POST value. If there are
|
|
jbe@0
|
665 several POST values with the given field name, then the first value is used.
|
|
jbe@0
|
666
|
|
jbe@35
|
667 Note: May be implemented through metamethods, but does support iteration
|
|
jbe@35
|
668 through pairs(...).
|
|
jbe@35
|
669
|
|
jbe@0
|
670
|
|
jbe@0
|
671 ### request.post_params_list
|
|
jbe@0
|
672
|
|
jbe@0
|
673 A table that maps field names to a sequence of their corresponding POST values.
|
|
jbe@0
|
674
|
|
jbe@35
|
675 Note: May be implemented through metamethods, but does support iteration
|
|
jbe@35
|
676 through pairs(...).
|
|
jbe@35
|
677
|
|
jbe@0
|
678
|
|
jbe@0
|
679 ### request.query
|
|
jbe@0
|
680
|
|
jbe@12
|
681 Query part of the request target including the leading question mark, e.g.
|
|
jbe@12
|
682 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
|
|
jbe@10
|
683 automatically parsed and made available through request.get_params and
|
|
jbe@10
|
684 request.get_params_list.
|
|
jbe@10
|
685
|
|
jbe@10
|
686 If there is no query part given in the request target, then this string is
|
|
jbe@10
|
687 the empty string. This value will be nil if (and only if) the request method
|
|
jbe@10
|
688 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
|
|
jbe@10
|
689 request-target in section 5.3.4 in RFC 7230).
|
|
jbe@0
|
690
|
|
jbe@0
|
691
|
|
jbe@0
|
692 ### request:process_request_body()
|
|
jbe@0
|
693
|
|
jbe@0
|
694 Starts processing the request body (if existent) to set the values
|
|
jbe@0
|
695 request.post_params, request.post_params_list, request.post_metadata, and
|
|
jbe@0
|
696 and request.post_metadata_list and/or to call POST field stream handlers that
|
|
jbe@0
|
697 have been previously registered with request:stream_post_param(...) or
|
|
jbe@0
|
698 request:stream_post_params(...).
|
|
jbe@0
|
699
|
|
jbe@0
|
700 This method gets invoked automatically when the POST param tables
|
|
jbe@0
|
701 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
|
|
jbe@0
|
702 deadlocks with the webbrowser). (Note: Automatic request body processing on
|
|
jbe@0
|
703 write may be disabled by calling request:defer_reading().)
|
|
jbe@0
|
704
|
|
jbe@0
|
705 After this method returned, all registered POST field stream handlers have
|
|
jbe@0
|
706 received all data. Registration of other POST field stream handlers is not
|
|
jbe@0
|
707 possible after this method has been called (or after request.post_params_list
|
|
jbe@0
|
708 or request.post_params have been accessed).
|
|
jbe@0
|
709
|
|
jbe@0
|
710
|
|
jbe@0
|
711 ### request:send_data(...)
|
|
jbe@0
|
712
|
|
jbe@0
|
713 Sends data as response body. All arguments are converted via tostring(...) and
|
|
jbe@0
|
714 concatenated. May be called multiple times until the request has been finished
|
|
jbe@0
|
715 by calling request:finish().
|
|
jbe@0
|
716
|
|
jbe@0
|
717 If the request method (see request.method) is "HEAD", then calls to
|
|
jbe@0
|
718 request:send_data(...) are automatically ignored.
|
|
jbe@0
|
719
|
|
jbe@0
|
720
|
|
jbe@0
|
721 ### request:send_header(key, value)
|
|
jbe@0
|
722
|
|
jbe@0
|
723 Sends a HTTP response header that consists of the given key and the given
|
|
jbe@0
|
724 value. Note: Key and value must be provided as separate arguments. Before any
|
|
jbe@0
|
725 headers can be sent, a HTTP status must have been set with
|
|
jbe@0
|
726 request:send_status(status_string).
|
|
jbe@0
|
727
|
|
jbe@0
|
728
|
|
jbe@0
|
729 ### request:send_status(status_string)
|
|
jbe@0
|
730
|
|
jbe@0
|
731 Sends a HTTP response status that is given as a string consisting of a 3-digit
|
|
jbe@0
|
732 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
|
|
jbe@0
|
733 function must be called once before any headers or response body data may be
|
|
jbe@0
|
734 sent.
|
|
jbe@0
|
735
|
|
jbe@0
|
736
|
|
jbe@0
|
737 ### request.socket
|
|
jbe@0
|
738
|
|
jbe@0
|
739 The underlaying socket. Can be used to force a TCP RST, etc.
|
|
jbe@0
|
740
|
|
jbe@0
|
741
|
|
jbe@0
|
742 ### request:stream_post_param(field_name, callback)
|
|
jbe@0
|
743
|
|
jbe@0
|
744 Registers a stream handler for the given POST parameter. The callback function
|
|
jbe@0
|
745 will be called in the following manner:
|
|
jbe@0
|
746
|
|
jbe@0
|
747 - For the initial chunk, the first chunk gets passed as first argument while a
|
|
jbe@0
|
748 table with metadata ("field_name" and "content_type") gets passed as second
|
|
jbe@0
|
749 argument. In case of an immediate EOF (i.e. an empty file), the passed
|
|
jbe@0
|
750 chunk is the empty string. In all other cases the chunk has a length greater
|
|
jbe@0
|
751 than zero.
|
|
jbe@0
|
752 - For any remaining chunks, the respective chunk gets passed as first and only
|
|
jbe@0
|
753 argument (no metadata). Here, the chunk has always a length greater than
|
|
jbe@0
|
754 zero.
|
|
jbe@0
|
755 - To indicate the end of the stream, the callback function is called without
|
|
jbe@0
|
756 arguments. This also happens in case of an immediate EOF (see above).
|
|
jbe@0
|
757
|
|
jbe@0
|
758 In case of an immediate EOF (i.e. an empty file), the callback function is thus
|
|
jbe@0
|
759 called as follows:
|
|
jbe@0
|
760
|
|
jbe@0
|
761 - The first time with an empty string as first argument, and with the metadata
|
|
jbe@0
|
762 as second argument.
|
|
jbe@0
|
763 - The second time without any arguments.
|
|
jbe@0
|
764
|
|
jbe@0
|
765
|
|
jbe@0
|
766 ### request:stream_post_params(pattern, callback)
|
|
jbe@0
|
767
|
|
jbe@0
|
768 Same as request:stream_post_param(...) but providing a string pattern to match
|
|
jbe@0
|
769 multiple field names (e.g. "^file_[0-9]+$").
|
|
jbe@0
|
770
|
|
jbe@0
|
771
|
|
jbe@0
|
772 ### request:stream_request_body(callback)
|
|
jbe@0
|
773
|
|
jbe@0
|
774 Start streaming of request body. For each chunk of the request body, the
|
|
jbe@0
|
775 callback function is called with the corresponding chunk. End of data is
|
|
jbe@0
|
776 indicated through return of request:stream_request_body(...) (not by calling
|
|
jbe@0
|
777 the callback without arguments).
|
|
jbe@0
|
778
|
|
jbe@44
|
779 The function may be called with nil instead of a callback function. In this
|
|
jbe@44
|
780 case, the request body is read and discarded. Only if nil is passed instead of
|
|
jbe@44
|
781 a callback, then the function may also be invoked when the request body has
|
|
jbe@44
|
782 already been read and/or processed. In the latter case, the function performs
|
|
jbe@44
|
783 no operation.
|
|
jbe@0
|
784
|
|
jbe@44
|
785
|