rev |
line source |
jbe@0
|
1
|
jbe@0
|
2 Moonbridge reference
|
jbe@0
|
3 ====================
|
jbe@0
|
4
|
jbe@0
|
5
|
jbe@0
|
6
|
jbe@0
|
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@0
|
24 Socket object passed to "connect" handler
|
jbe@0
|
25 -----------------------------------------
|
jbe@0
|
26
|
jbe@0
|
27 For every incoming connection, the registered "connect" handler is called with
|
jbe@0
|
28 a single socket object as argument, which is described below:
|
jbe@0
|
29
|
jbe@0
|
30
|
jbe@0
|
31 ### socket:cancel()
|
jbe@0
|
32
|
jbe@0
|
33 Closes the socket connection by sending a TCP RST package if possible to
|
jbe@0
|
34 indicate error condition.
|
jbe@0
|
35
|
jbe@0
|
36 Warning: Previously sent (and flushed) data may be lost during transmission.
|
jbe@0
|
37
|
jbe@0
|
38
|
jbe@0
|
39 ### socket:close(timeout)
|
jbe@0
|
40
|
jbe@0
|
41 Closes the socket connection (input and output stream) by flushing all data and
|
jbe@0
|
42 sending a TCP FIN package. Performs no operation if stream has already been
|
jbe@0
|
43 closed.
|
jbe@0
|
44
|
jbe@0
|
45 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
|
jbe@0
|
46 depending on the particular operating system used. All pending input data
|
jbe@0
|
47 should have been read before calling socket:close().
|
jbe@0
|
48
|
jbe@0
|
49 The optional timeout parameter may be used to wait until all data has been sent
|
jbe@0
|
50 out, or until the timeout elapses (in which case a TCP RST is sent) whichever
|
jbe@0
|
51 happens first. A timeout value of 0 or nil causes immediate return and sending
|
jbe@0
|
52 of pending data in background (recommended).
|
jbe@0
|
53
|
jbe@0
|
54
|
jbe@0
|
55 ### socket:flush()
|
jbe@0
|
56
|
jbe@0
|
57 Alias for socket.output:flush()
|
jbe@0
|
58
|
jbe@0
|
59
|
jbe@0
|
60 ### socket.input
|
jbe@0
|
61
|
jbe@0
|
62 Lua file handle representing the input stream of the socket connection.
|
jbe@0
|
63 Supports the same methods as io.open()'s return values.
|
jbe@0
|
64
|
jbe@0
|
65
|
jbe@0
|
66 ### socket.interval
|
jbe@0
|
67
|
jbe@0
|
68 Set to the name of an interval timer if the "connect" handler was called due to
|
jbe@0
|
69 an elapsed interval timer. Otherwise nil.
|
jbe@0
|
70
|
jbe@0
|
71
|
jbe@0
|
72 ### socket:lines()
|
jbe@0
|
73
|
jbe@0
|
74 Alias for socket.input:lines()
|
jbe@0
|
75
|
jbe@0
|
76
|
jbe@0
|
77 ### socket.local_ip4
|
jbe@0
|
78
|
jbe@0
|
79 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
|
jbe@0
|
80 string.
|
jbe@0
|
81
|
jbe@0
|
82
|
jbe@0
|
83 ### socket.local_ip6
|
jbe@0
|
84
|
jbe@0
|
85 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
|
jbe@0
|
86 a string.
|
jbe@0
|
87
|
jbe@0
|
88
|
jbe@0
|
89 ### socket.local_tcpport
|
jbe@0
|
90
|
jbe@0
|
91 Local TCP port used for the connection.
|
jbe@0
|
92
|
jbe@0
|
93
|
jbe@0
|
94 ### socket.output
|
jbe@0
|
95
|
jbe@0
|
96 Lua file handle representing the output stream of the socket connection.
|
jbe@0
|
97 Supports the same methods as io.open()'s return values.
|
jbe@0
|
98
|
jbe@0
|
99
|
jbe@0
|
100 ### socket:read(...)
|
jbe@0
|
101
|
jbe@0
|
102 Alias for socket.input:read()
|
jbe@0
|
103
|
jbe@0
|
104
|
jbe@0
|
105 ### socket:readuntil(terminator, maxlen)
|
jbe@0
|
106
|
jbe@0
|
107 Reads as many bytes until a byte equal to the terminator value occurs. An
|
jbe@0
|
108 optional maximum length may be specified. The terminating byte is included in
|
jbe@0
|
109 the return value (unless the maximum length would be exceeded).
|
jbe@0
|
110
|
jbe@0
|
111 Also available as :readuntil(...) method for any other Lua file handle
|
jbe@0
|
112 (including socket.input)
|
jbe@0
|
113
|
jbe@0
|
114
|
jbe@0
|
115 ### socket.remote_ip4
|
jbe@0
|
116
|
jbe@0
|
117 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
|
jbe@0
|
118 a string.
|
jbe@0
|
119
|
jbe@0
|
120
|
jbe@0
|
121 ### socket.remote_ip6
|
jbe@0
|
122
|
jbe@0
|
123 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
|
jbe@0
|
124 a string.
|
jbe@0
|
125
|
jbe@0
|
126
|
jbe@0
|
127 ### socket.remote_tcpport
|
jbe@0
|
128
|
jbe@0
|
129 Remote TCP port used for the connection.
|
jbe@0
|
130
|
jbe@0
|
131
|
jbe@0
|
132 ### socket:write(...)
|
jbe@0
|
133
|
jbe@0
|
134 Alias for socket.output:write(...)
|
jbe@0
|
135
|
jbe@0
|
136
|
jbe@0
|
137
|
jbe@0
|
138 HTTP module
|
jbe@0
|
139 -----------
|
jbe@0
|
140
|
jbe@0
|
141 The http module exports the function http.generate_handler(callback) that
|
jbe@0
|
142 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
|
jbe@0
|
143 example of invocation. A table with options may be passed either as a second
|
jbe@0
|
144 argument, or as a first argument preceeding the callback function (whichever is
|
jbe@0
|
145 more convenient).
|
jbe@0
|
146
|
jbe@0
|
147 The following options are supported:
|
jbe@0
|
148
|
jbe@0
|
149 - request_body_size_limit: maximum size of payload of HTTP request body
|
jbe@0
|
150 (transfer encoding is allowed to add a limited amount of extra data)
|
jbe@0
|
151 - chunk_size: optional default value for maximum_input_chunk_size and
|
jbe@0
|
152 minimum_output_chunk_size
|
jbe@0
|
153 - request_header_size_limit: maximum size of HTTP request headers
|
jbe@0
|
154 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
|
jbe@0
|
155 certain POST fields (bigger chunks will be fragmented automatically)
|
jbe@0
|
156 - minimum_output_chunk_size: minimum size for a chunk when sending a response
|
jbe@0
|
157 body (smaller chunks will be buffered and concatenated with future data;
|
jbe@0
|
158 ignored when request:flush() is called)
|
jbe@0
|
159 - static_headers: a set of headers to be included in every HTTP response
|
jbe@0
|
160 (may be a string, a table or strings, or a table of key-value pairs)
|
jbe@0
|
161
|
jbe@0
|
162 The callback function receives a single request object as argument, which is
|
jbe@0
|
163 described below.
|
jbe@0
|
164
|
jbe@0
|
165
|
jbe@0
|
166 ### request.body
|
jbe@0
|
167
|
jbe@0
|
168 The request body (without headers) as a string. Accessing this value makes
|
jbe@0
|
169 further access to request.post_params and request.post_params_list, or
|
jbe@0
|
170 invocation of request:stream_request_body(...) impossible.
|
jbe@0
|
171
|
jbe@0
|
172
|
jbe@0
|
173 ### request.cookies
|
jbe@0
|
174
|
jbe@0
|
175 A table with all cookies sent by the client.
|
jbe@0
|
176
|
jbe@0
|
177
|
jbe@0
|
178 ### request.defer_reading()
|
jbe@0
|
179
|
jbe@0
|
180 Disables automatic request body processing on write. Can be called before
|
jbe@0
|
181 sending a HTTP status code to send a response before the request has been fully
|
jbe@0
|
182 received.
|
jbe@0
|
183
|
jbe@0
|
184 CAUTION: Responding to a request before the request body has been processed may
|
jbe@0
|
185 lead to a deadlock if the browser does not process the response while trying to
|
jbe@0
|
186 send the request. Therefore, this function should only be used if:
|
jbe@0
|
187
|
jbe@0
|
188 - the TCP stack has enough buffer space for the response (i.e. if the response
|
jbe@0
|
189 is small enough), and if
|
jbe@0
|
190 - a timer is used to cancel the response in case of a deadlock.
|
jbe@0
|
191
|
jbe@0
|
192 It is recommended to not use this function unless certain performance tweaks
|
jbe@0
|
193 are desired.
|
jbe@0
|
194
|
jbe@0
|
195
|
jbe@0
|
196 ### request:finish()
|
jbe@0
|
197
|
jbe@0
|
198 Finishes and flushes a HTTP response. May be called multiple times. An
|
jbe@0
|
199 HTTP status, all headers, and the response body (if applicable) must have been
|
jbe@0
|
200 previously sent. After calling this method, no further data may be written.
|
jbe@0
|
201
|
jbe@0
|
202
|
jbe@0
|
203 ### request:finish_headers()
|
jbe@0
|
204
|
jbe@0
|
205 Finishes and flushes the HTTP response header section. May be called multiple
|
jbe@0
|
206 times, as long as the request is not finished completely. This method is
|
jbe@0
|
207 automatically invoked if the application is beginning to send a response body.
|
jbe@0
|
208 After calling this method, no further headers may be sent.
|
jbe@0
|
209
|
jbe@0
|
210
|
jbe@0
|
211 ### request:flush()
|
jbe@0
|
212
|
jbe@0
|
213 Flushes any pending output data. Note: In order to mark the end of a response
|
jbe@0
|
214 body, it is required to call request:finish().
|
jbe@0
|
215
|
jbe@0
|
216
|
jbe@0
|
217 ### request.get_params
|
jbe@0
|
218
|
jbe@0
|
219 A table that maps field names to their corresponding GET value. If there are
|
jbe@0
|
220 several GET values with the given field name, then the first value is used.
|
jbe@0
|
221
|
jbe@0
|
222
|
jbe@0
|
223 ### request.get_params_list
|
jbe@0
|
224
|
jbe@0
|
225 A table that maps field names to a sequence of their corresponding GET values.
|
jbe@0
|
226
|
jbe@0
|
227
|
jbe@0
|
228 ### request.headers
|
jbe@0
|
229
|
jbe@0
|
230 A table that maps (case-insensitively) a HTTP header field name to a sequence
|
jbe@0
|
231 of values. One entry is created for every occurrence of a header line with the
|
jbe@0
|
232 given field name).
|
jbe@0
|
233
|
jbe@0
|
234
|
jbe@0
|
235 ### request.headers_csv_string
|
jbe@0
|
236
|
jbe@0
|
237 A table that maps (case-insensitively) a HTTP header field name to a comma
|
jbe@0
|
238 separated string. Multiple occurrences of the header with the given field name
|
jbe@0
|
239 are automatically merged into the comma separated string.
|
jbe@0
|
240
|
jbe@0
|
241
|
jbe@0
|
242 ### request.headers_csv_table
|
jbe@0
|
243
|
jbe@0
|
244 A table that maps (case-insensitively) a HTTP header field name to a sequence
|
jbe@0
|
245 of values. One entry is created for every comma separated value of each header
|
jbe@0
|
246 with the given field name.
|
jbe@0
|
247
|
jbe@0
|
248
|
jbe@0
|
249 ### request.headers_flags
|
jbe@0
|
250
|
jbe@0
|
251 A table that maps (case-insensitively) a HTTP header field name to another
|
jbe@0
|
252 table which (again case-insensitively) maps a string to a boolean, depending on
|
jbe@0
|
253 whether this string occurred in the list of comma separated values of one
|
jbe@0
|
254 header line with the given field name that was the key in the first table.
|
jbe@0
|
255
|
jbe@0
|
256
|
jbe@0
|
257 ### request.headers_value
|
jbe@0
|
258
|
jbe@0
|
259 A table that maps (case-insensitively) a HTTP header field name to a value. If
|
jbe@0
|
260 multiple header lines with the given field name have been received, false is
|
jbe@0
|
261 used as value.
|
jbe@0
|
262
|
jbe@0
|
263
|
jbe@0
|
264 ### request.method
|
jbe@0
|
265
|
jbe@0
|
266 The HTTP request method, e.g. "HEAD", "GET", or "POST".
|
jbe@0
|
267
|
jbe@0
|
268
|
jbe@0
|
269 ### request.path
|
jbe@0
|
270
|
jbe@10
|
271 The requested path without a leading slash and without the query part (e.g.
|
jbe@10
|
272 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
|
jbe@10
|
273 see request.query.
|
jbe@10
|
274
|
jbe@10
|
275 This value will be nil if (and only if) the request method is "OPTIONS" with a
|
jbe@10
|
276 request target equal to "*" (see also asterisk-form of request-target in
|
jbe@10
|
277 section 5.3.4 in RFC 7230).
|
jbe@0
|
278
|
jbe@0
|
279
|
jbe@0
|
280 ### request.post_metadata
|
jbe@0
|
281
|
jbe@0
|
282 Only set for multipart/form-data POST requests. A table that maps field names
|
jbe@0
|
283 to their corresponding POST metadata table which contains two entries:
|
jbe@0
|
284 "file_name" and "content_type". If there are several POST values with the given
|
jbe@0
|
285 field name, then the first value/file is used.
|
jbe@0
|
286
|
jbe@0
|
287
|
jbe@0
|
288 ### request.post_metadata_list
|
jbe@0
|
289
|
jbe@0
|
290 Only set for multipart/form-data POST requests. A table that maps field names
|
jbe@0
|
291 to a sequence with their corresponding POST metadata tables. Needed if multiple
|
jbe@0
|
292 files are uploaded with the same field name.
|
jbe@0
|
293
|
jbe@0
|
294
|
jbe@0
|
295 ### request.post_params
|
jbe@0
|
296
|
jbe@0
|
297 A table that maps field names to their corresponding POST value. If there are
|
jbe@0
|
298 several POST values with the given field name, then the first value is used.
|
jbe@0
|
299
|
jbe@0
|
300
|
jbe@0
|
301 ### request.post_params_list
|
jbe@0
|
302
|
jbe@0
|
303 A table that maps field names to a sequence of their corresponding POST values.
|
jbe@0
|
304
|
jbe@0
|
305
|
jbe@0
|
306 ### request.query
|
jbe@0
|
307
|
jbe@12
|
308 Query part of the request target including the leading question mark, e.g.
|
jbe@12
|
309 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
|
jbe@10
|
310 automatically parsed and made available through request.get_params and
|
jbe@10
|
311 request.get_params_list.
|
jbe@10
|
312
|
jbe@10
|
313 If there is no query part given in the request target, then this string is
|
jbe@10
|
314 the empty string. This value will be nil if (and only if) the request method
|
jbe@10
|
315 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
|
jbe@10
|
316 request-target in section 5.3.4 in RFC 7230).
|
jbe@0
|
317
|
jbe@0
|
318
|
jbe@0
|
319 ### request:process_request_body()
|
jbe@0
|
320
|
jbe@0
|
321 Starts processing the request body (if existent) to set the values
|
jbe@0
|
322 request.post_params, request.post_params_list, request.post_metadata, and
|
jbe@0
|
323 and request.post_metadata_list and/or to call POST field stream handlers that
|
jbe@0
|
324 have been previously registered with request:stream_post_param(...) or
|
jbe@0
|
325 request:stream_post_params(...).
|
jbe@0
|
326
|
jbe@0
|
327 This method gets invoked automatically when the POST param tables
|
jbe@0
|
328 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
|
jbe@0
|
329 deadlocks with the webbrowser). (Note: Automatic request body processing on
|
jbe@0
|
330 write may be disabled by calling request:defer_reading().)
|
jbe@0
|
331
|
jbe@0
|
332 After this method returned, all registered POST field stream handlers have
|
jbe@0
|
333 received all data. Registration of other POST field stream handlers is not
|
jbe@0
|
334 possible after this method has been called (or after request.post_params_list
|
jbe@0
|
335 or request.post_params have been accessed).
|
jbe@0
|
336
|
jbe@0
|
337
|
jbe@0
|
338 ### request:send_data(...)
|
jbe@0
|
339
|
jbe@0
|
340 Sends data as response body. All arguments are converted via tostring(...) and
|
jbe@0
|
341 concatenated. May be called multiple times until the request has been finished
|
jbe@0
|
342 by calling request:finish().
|
jbe@0
|
343
|
jbe@0
|
344 If the request method (see request.method) is "HEAD", then calls to
|
jbe@0
|
345 request:send_data(...) are automatically ignored.
|
jbe@0
|
346
|
jbe@0
|
347
|
jbe@0
|
348 ### request:send_header(key, value)
|
jbe@0
|
349
|
jbe@0
|
350 Sends a HTTP response header that consists of the given key and the given
|
jbe@0
|
351 value. Note: Key and value must be provided as separate arguments. Before any
|
jbe@0
|
352 headers can be sent, a HTTP status must have been set with
|
jbe@0
|
353 request:send_status(status_string).
|
jbe@0
|
354
|
jbe@0
|
355
|
jbe@0
|
356 ### request:send_status(status_string)
|
jbe@0
|
357
|
jbe@0
|
358 Sends a HTTP response status that is given as a string consisting of a 3-digit
|
jbe@0
|
359 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
|
jbe@0
|
360 function must be called once before any headers or response body data may be
|
jbe@0
|
361 sent.
|
jbe@0
|
362
|
jbe@0
|
363
|
jbe@14
|
364 ### request:send_text_status_response(status_string, text)
|
jbe@14
|
365
|
jbe@14
|
366 Sends a HTTP status plus a response body of content-type "text/plain" and
|
jbe@14
|
367 finishes the request using request:finish(). The status_string has to be
|
jbe@14
|
368 provided in the same format as expected by request:send_status(...) and will
|
jbe@14
|
369 be included in the response body as plain text. The additional second "text"
|
jbe@14
|
370 argument will be appended to the reponse body (separated by an empty line) if
|
jbe@14
|
371 given.
|
jbe@14
|
372
|
jbe@14
|
373
|
jbe@0
|
374 ### request.socket
|
jbe@0
|
375
|
jbe@0
|
376 The underlaying socket. Can be used to force a TCP RST, etc.
|
jbe@0
|
377
|
jbe@0
|
378
|
jbe@0
|
379 ### request:stream_post_param(field_name, callback)
|
jbe@0
|
380
|
jbe@0
|
381 Registers a stream handler for the given POST parameter. The callback function
|
jbe@0
|
382 will be called in the following manner:
|
jbe@0
|
383
|
jbe@0
|
384 - For the initial chunk, the first chunk gets passed as first argument while a
|
jbe@0
|
385 table with metadata ("field_name" and "content_type") gets passed as second
|
jbe@0
|
386 argument. In case of an immediate EOF (i.e. an empty file), the passed
|
jbe@0
|
387 chunk is the empty string. In all other cases the chunk has a length greater
|
jbe@0
|
388 than zero.
|
jbe@0
|
389 - For any remaining chunks, the respective chunk gets passed as first and only
|
jbe@0
|
390 argument (no metadata). Here, the chunk has always a length greater than
|
jbe@0
|
391 zero.
|
jbe@0
|
392 - To indicate the end of the stream, the callback function is called without
|
jbe@0
|
393 arguments. This also happens in case of an immediate EOF (see above).
|
jbe@0
|
394
|
jbe@0
|
395 In case of an immediate EOF (i.e. an empty file), the callback function is thus
|
jbe@0
|
396 called as follows:
|
jbe@0
|
397
|
jbe@0
|
398 - The first time with an empty string as first argument, and with the metadata
|
jbe@0
|
399 as second argument.
|
jbe@0
|
400 - The second time without any arguments.
|
jbe@0
|
401
|
jbe@0
|
402
|
jbe@0
|
403 ### request:stream_post_params(pattern, callback)
|
jbe@0
|
404
|
jbe@0
|
405 Same as request:stream_post_param(...) but providing a string pattern to match
|
jbe@0
|
406 multiple field names (e.g. "^file_[0-9]+$").
|
jbe@0
|
407
|
jbe@0
|
408
|
jbe@0
|
409 ### request:stream_request_body(callback)
|
jbe@0
|
410
|
jbe@0
|
411 Start streaming of request body. For each chunk of the request body, the
|
jbe@0
|
412 callback function is called with the corresponding chunk. End of data is
|
jbe@0
|
413 indicated through return of request:stream_request_body(...) (not by calling
|
jbe@0
|
414 the callback without arguments).
|
jbe@0
|
415
|
jbe@0
|
416
|