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