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@91
|
73 number of discarded bytes. If no bytes could be read but EOF was encountered,
|
jbe@91
|
74 then true is returned.
|
jbe@91
|
75
|
jbe@91
|
76 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
77 second result value) are returned.
|
jbe@0
|
78
|
jbe@0
|
79
|
jbe@91
|
80 ### socket:drain_nb(maxlen, terminator)
|
jbe@0
|
81
|
jbe@91
|
82 Same as socket:read_nb(maxlen, terminator), but discards the input and returns
|
jbe@91
|
83 the number of discarded bytes. If no bytes could be read but EOF was
|
jbe@91
|
84 encountered, then true is returned.
|
jbe@91
|
85
|
jbe@91
|
86 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
87 second result value) are returned.
|
jbe@91
|
88
|
jbe@0
|
89
|
jbe@94
|
90 ### socket:finish()
|
jbe@94
|
91
|
jbe@94
|
92 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
|
jbe@94
|
93 still possible. When there is no more input data to be read, the connection
|
jbe@94
|
94 should finally be closed with socket:close().
|
jbe@94
|
95
|
jbe@94
|
96 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
|
jbe@94
|
97 the underlying socket and emulates EOF on subsequent reads. Also in this case,
|
jbe@94
|
98 the connection should be finally closed with socket:close().
|
jbe@94
|
99
|
jbe@94
|
100
|
jbe@91
|
101 ### socket:flush(...)
|
jbe@91
|
102
|
jbe@91
|
103 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
|
jbe@91
|
104 data is passed to the operating system).
|
jbe@91
|
105
|
jbe@91
|
106 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
107 second result value) are returned. On success, the socket userdata object is
|
jbe@91
|
108 returned.
|
jbe@91
|
109
|
jbe@0
|
110
|
jbe@91
|
111 ### socket:flush_nb(...)
|
jbe@91
|
112
|
jbe@91
|
113 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
|
jbe@91
|
114 pending data is passed to the operating system). The total number of bytes that
|
jbe@91
|
115 could not be passed yet to the operating system is returned. Zero is returned
|
jbe@91
|
116 if all data could be flushed out.
|
jbe@91
|
117
|
jbe@91
|
118 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
119 second result value) are returned.
|
jbe@0
|
120
|
jbe@0
|
121
|
jbe@0
|
122 ### socket.interval
|
jbe@0
|
123
|
jbe@0
|
124 Set to the name of an interval timer if the "connect" handler was called due to
|
jbe@0
|
125 an elapsed interval timer. Otherwise nil.
|
jbe@0
|
126
|
jbe@0
|
127
|
jbe@0
|
128 ### socket.local_ip4
|
jbe@0
|
129
|
jbe@0
|
130 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
|
jbe@0
|
131 string.
|
jbe@0
|
132
|
jbe@0
|
133
|
jbe@0
|
134 ### socket.local_ip6
|
jbe@0
|
135
|
jbe@0
|
136 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
|
jbe@0
|
137 a string.
|
jbe@0
|
138
|
jbe@0
|
139
|
jbe@0
|
140 ### socket.local_tcpport
|
jbe@0
|
141
|
jbe@0
|
142 Local TCP port used for the connection.
|
jbe@0
|
143
|
jbe@0
|
144
|
jbe@91
|
145 ### socket:read(maxlen, terminator)
|
jbe@0
|
146
|
jbe@91
|
147 Read up to maxlen bytes or until an optional termination character is
|
jbe@91
|
148 encountered (which is included in the result). The maxlen value may be nil, in
|
jbe@91
|
149 which case there is no limit on the number of bytes read.
|
jbe@0
|
150
|
jbe@91
|
151 If EOF is encountered before any data could be read, then false (as first
|
jbe@91
|
152 return value) plus a notice string (as second return value) are returned.
|
jbe@0
|
153
|
jbe@91
|
154 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
155 second result value) are returned.
|
jbe@0
|
156
|
jbe@0
|
157
|
jbe@91
|
158 ### socket:read_nb(maxlen, terminator)
|
jbe@91
|
159
|
jbe@91
|
160 Read up to maxlen bytes, until an optional termination character is encountered
|
jbe@91
|
161 (which is included in the result), or until no more data is available for
|
jbe@91
|
162 reading. The maxlen value may be nil, in which case there is no limit on the
|
jbe@91
|
163 number of bytes read.
|
jbe@78
|
164
|
jbe@91
|
165 If EOF is encountered before any data could be read, then false (as first
|
jbe@91
|
166 return value) plus a notice string (as second return value) are returned.
|
jbe@78
|
167
|
jbe@91
|
168 If no data was available for reading, but no EOF was encountered, then an empty
|
jbe@91
|
169 string is returned.
|
jbe@91
|
170
|
jbe@91
|
171 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
172 second result value) are returned.
|
jbe@78
|
173
|
jbe@78
|
174
|
jbe@0
|
175 ### socket.remote_ip4
|
jbe@0
|
176
|
jbe@0
|
177 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
|
jbe@0
|
178 a string.
|
jbe@0
|
179
|
jbe@0
|
180
|
jbe@0
|
181 ### socket.remote_ip6
|
jbe@0
|
182
|
jbe@0
|
183 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
|
jbe@0
|
184 a string.
|
jbe@0
|
185
|
jbe@0
|
186
|
jbe@0
|
187 ### socket.remote_tcpport
|
jbe@0
|
188
|
jbe@0
|
189 Remote TCP port used for the connection.
|
jbe@0
|
190
|
jbe@0
|
191
|
jbe@91
|
192 ### socket:reset()
|
jbe@91
|
193
|
jbe@91
|
194 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
|
jbe@91
|
195 packet if possible to indicate error condition.
|
jbe@91
|
196
|
jbe@91
|
197 Returns true on success, or nil (as first result value) plus error message (as
|
jbe@91
|
198 second result value) in case of an I/O error. Using this method on sockets that
|
jbe@91
|
199 have already been closed (or reset) will throw an error.
|
jbe@91
|
200
|
jbe@91
|
201 Warning: Previously sent (and flushed) data may be lost during transmission.
|
jbe@91
|
202
|
jbe@91
|
203
|
jbe@0
|
204 ### socket:write(...)
|
jbe@0
|
205
|
jbe@91
|
206 Takes a variable number of strings and sends them to the peer. The operation is
|
jbe@91
|
207 buffered, so to actually send out the data, it is necessary to eventually call
|
jbe@91
|
208 socket:flush(), socket:finish(), or socket:close().
|
jbe@91
|
209
|
jbe@91
|
210 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
211 second result value) are returned. On success, the socket userdata object is
|
jbe@91
|
212 returned.
|
jbe@91
|
213
|
jbe@91
|
214
|
jbe@91
|
215 ### socket:write_nb(...)
|
jbe@91
|
216
|
jbe@91
|
217 Takes a variable number of strings and sends them to the peer. The operation is
|
jbe@91
|
218 buffered, so to actually send out the data, it is necessary to eventually call
|
jbe@91
|
219 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
|
jbe@91
|
220
|
jbe@91
|
221 This function always returns immediately (i.e. it does not block). If all data
|
jbe@91
|
222 (but a small buffered portion) could be sent out, then zero is returned.
|
jbe@91
|
223 Otherwise, all arguments that could not be sent are stored in a buffer of
|
jbe@91
|
224 unlimited size (up to memory capabilities) and an integer is returned that
|
jbe@91
|
225 indicates the number of bytes currently in the buffer.
|
jbe@91
|
226
|
jbe@91
|
227 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@91
|
228 second result value) are returned.
|
jbe@0
|
229
|
jbe@0
|
230
|
jbe@0
|
231
|
jbe@98
|
232 I/O library
|
jbe@98
|
233 -----------
|
jbe@98
|
234
|
jbe@98
|
235 The Moonbridge Network Server for Lua Applications comes with its own I/O
|
jbe@98
|
236 library to support blocking as well as nonblocking I/O operations.
|
jbe@98
|
237
|
jbe@98
|
238
|
jbe@106
|
239 ### moonbridge_io.poll(input_set, output_set, timeout)
|
jbe@106
|
240
|
jbe@106
|
241 This function waits for at least one of the given file descriptors and/or
|
jbe@106
|
242 I/O handles to be ready for input or output. The two sets of file descriptors
|
jbe@106
|
243 and/or handles must contain the file descriptor or handle as a key, and a value
|
jbe@106
|
244 which does evaluate to true. If a set is nil, it is treated as being empty.
|
jbe@106
|
245
|
jbe@106
|
246 Returns true when at least one file descriptor or handle is ready for reading
|
jbe@106
|
247 or writing respectively. Returns false (as first return value) plus a status
|
jbe@106
|
248 message (as second return value) in case of timeout or when a signal was
|
jbe@106
|
249 received.
|
jbe@106
|
250
|
jbe@106
|
251
|
jbe@98
|
252 ### moonbridge_io.tcpconnect(hostname, port)
|
jbe@98
|
253
|
jbe@98
|
254 Tries to open a TCP connection with the given host and TCP port number. Returns
|
jbe@98
|
255 a socket object on success (methods see above), or nil (as first return value)
|
jbe@98
|
256 plus an error message (as second return value) in case of error.
|
jbe@98
|
257
|
jbe@98
|
258
|
jbe@99
|
259 ### moonbridge_io.tcpconnect_nb(hostname, port)
|
jbe@99
|
260
|
jbe@99
|
261 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
|
jbe@99
|
262 does not block and immediately returns a socket object.
|
jbe@99
|
263
|
jbe@102
|
264 Note: The current implementation still blocks during the DNS lookup. Use a
|
jbe@102
|
265 numeric IP address as hostname to be truly nonblocking.
|
jbe@102
|
266
|
jbe@99
|
267 In case of an I/O error, nil (as first return value) plus an error message (as
|
jbe@99
|
268 second result value) may be returned. However, connection errors may also be
|
jbe@99
|
269 reported on first read or write on the socket.
|
jbe@99
|
270
|
jbe@99
|
271
|
jbe@98
|
272
|
jbe@0
|
273 HTTP module
|
jbe@0
|
274 -----------
|
jbe@0
|
275
|
jbe@0
|
276 The http module exports the function http.generate_handler(callback) that
|
jbe@0
|
277 converts an HTTP handler to a "connect" handler. See file "example.lua" for an
|
jbe@0
|
278 example of invocation. A table with options may be passed either as a second
|
jbe@0
|
279 argument, or as a first argument preceeding the callback function (whichever is
|
jbe@0
|
280 more convenient).
|
jbe@0
|
281
|
jbe@0
|
282 The following options are supported:
|
jbe@0
|
283
|
jbe@0
|
284 - request_body_size_limit: maximum size of payload of HTTP request body
|
jbe@0
|
285 (transfer encoding is allowed to add a limited amount of extra data)
|
jbe@0
|
286 - chunk_size: optional default value for maximum_input_chunk_size and
|
jbe@0
|
287 minimum_output_chunk_size
|
jbe@0
|
288 - request_header_size_limit: maximum size of HTTP request headers
|
jbe@0
|
289 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
|
jbe@0
|
290 certain POST fields (bigger chunks will be fragmented automatically)
|
jbe@0
|
291 - minimum_output_chunk_size: minimum size for a chunk when sending a response
|
jbe@0
|
292 body (smaller chunks will be buffered and concatenated with future data;
|
jbe@0
|
293 ignored when request:flush() is called)
|
jbe@0
|
294 - static_headers: a set of headers to be included in every HTTP response
|
jbe@0
|
295 (may be a string, a table or strings, or a table of key-value pairs)
|
jbe@0
|
296
|
jbe@0
|
297 The callback function receives a single request object as argument, which is
|
jbe@0
|
298 described below.
|
jbe@0
|
299
|
jbe@0
|
300
|
jbe@0
|
301 ### request.body
|
jbe@0
|
302
|
jbe@0
|
303 The request body (without headers) as a string. Accessing this value makes
|
jbe@0
|
304 further access to request.post_params and request.post_params_list, or
|
jbe@0
|
305 invocation of request:stream_request_body(...) impossible.
|
jbe@0
|
306
|
jbe@0
|
307
|
jbe@60
|
308 ### request:close_after_finish()
|
jbe@60
|
309
|
jbe@60
|
310 Closes the connection after answering the request.
|
jbe@60
|
311
|
jbe@60
|
312 This method can only be called before the HTTP response header section has been
|
jbe@60
|
313 finished (i.e. before request:finish_headers(), request:send_data(...), or
|
jbe@60
|
314 request:finish() were called), but it may be called before a status code has
|
jbe@60
|
315 been sent using request:send_status(...).
|
jbe@60
|
316
|
jbe@60
|
317 A corresponding "Connection: close" header is automatically sent.
|
jbe@60
|
318
|
jbe@60
|
319
|
jbe@0
|
320 ### request.cookies
|
jbe@0
|
321
|
jbe@0
|
322 A table with all cookies sent by the client.
|
jbe@0
|
323
|
jbe@0
|
324
|
jbe@0
|
325 ### request.defer_reading()
|
jbe@0
|
326
|
jbe@0
|
327 Disables automatic request body processing on write. Can be called before
|
jbe@0
|
328 sending a HTTP status code to send a response before the request has been fully
|
jbe@0
|
329 received.
|
jbe@0
|
330
|
jbe@0
|
331 CAUTION: Responding to a request before the request body has been processed may
|
jbe@0
|
332 lead to a deadlock if the browser does not process the response while trying to
|
jbe@0
|
333 send the request. Therefore, this function should only be used if:
|
jbe@0
|
334
|
jbe@0
|
335 - the TCP stack has enough buffer space for the response (i.e. if the response
|
jbe@0
|
336 is small enough), and if
|
jbe@0
|
337 - a timer is used to cancel the response in case of a deadlock.
|
jbe@0
|
338
|
jbe@0
|
339 It is recommended to not use this function unless certain performance tweaks
|
jbe@0
|
340 are desired.
|
jbe@0
|
341
|
jbe@0
|
342
|
jbe@50
|
343 ### request.faulty
|
jbe@50
|
344
|
jbe@50
|
345 Normally set to false. In case of a read or write error on the client
|
jbe@50
|
346 connection, this value is set to true before a Lua error is raised.
|
jbe@50
|
347
|
jbe@50
|
348 A faulty request handle must not be used, or another Lua error will be raised.
|
jbe@50
|
349
|
jbe@50
|
350
|
jbe@0
|
351 ### request:finish()
|
jbe@0
|
352
|
jbe@0
|
353 Finishes and flushes a HTTP response. May be called multiple times. An
|
jbe@0
|
354 HTTP status, all headers, and the response body (if applicable) must have been
|
jbe@0
|
355 previously sent. After calling this method, no further data may be written.
|
jbe@0
|
356
|
jbe@0
|
357
|
jbe@0
|
358 ### request:finish_headers()
|
jbe@0
|
359
|
jbe@0
|
360 Finishes and flushes the HTTP response header section. May be called multiple
|
jbe@0
|
361 times, as long as the request is not finished completely. This method is
|
jbe@0
|
362 automatically invoked if the application is beginning to send a response body.
|
jbe@0
|
363 After calling this method, no further headers may be sent.
|
jbe@0
|
364
|
jbe@0
|
365
|
jbe@0
|
366 ### request:flush()
|
jbe@0
|
367
|
jbe@0
|
368 Flushes any pending output data. Note: In order to mark the end of a response
|
jbe@0
|
369 body, it is required to call request:finish().
|
jbe@0
|
370
|
jbe@0
|
371
|
jbe@0
|
372 ### request.get_params
|
jbe@0
|
373
|
jbe@0
|
374 A table that maps field names to their corresponding GET value. If there are
|
jbe@0
|
375 several GET values with the given field name, then the first value is used.
|
jbe@0
|
376
|
jbe@35
|
377 Note: May be implemented through metamethods, but does support iteration
|
jbe@35
|
378 through pairs(...).
|
jbe@35
|
379
|
jbe@0
|
380
|
jbe@0
|
381 ### request.get_params_list
|
jbe@0
|
382
|
jbe@0
|
383 A table that maps field names to a sequence of their corresponding GET values.
|
jbe@0
|
384
|
jbe@35
|
385 Note: May be implemented through metamethods, but does support iteration
|
jbe@35
|
386 through pairs(...).
|
jbe@35
|
387
|
jbe@0
|
388
|
jbe@0
|
389 ### request.headers
|
jbe@0
|
390
|
jbe@0
|
391 A table that maps (case-insensitively) a HTTP header field name to a sequence
|
jbe@0
|
392 of values. One entry is created for every occurrence of a header line with the
|
jbe@0
|
393 given field name).
|
jbe@0
|
394
|
jbe@0
|
395
|
jbe@0
|
396 ### request.headers_csv_string
|
jbe@0
|
397
|
jbe@0
|
398 A table that maps (case-insensitively) a HTTP header field name to a comma
|
jbe@0
|
399 separated string. Multiple occurrences of the header with the given field name
|
jbe@0
|
400 are automatically merged into the comma separated string.
|
jbe@0
|
401
|
jbe@0
|
402
|
jbe@0
|
403 ### request.headers_csv_table
|
jbe@0
|
404
|
jbe@0
|
405 A table that maps (case-insensitively) a HTTP header field name to a sequence
|
jbe@0
|
406 of values. One entry is created for every comma separated value of each header
|
jbe@0
|
407 with the given field name.
|
jbe@0
|
408
|
jbe@0
|
409
|
jbe@0
|
410 ### request.headers_flags
|
jbe@0
|
411
|
jbe@0
|
412 A table that maps (case-insensitively) a HTTP header field name to another
|
jbe@0
|
413 table which (again case-insensitively) maps a string to a boolean, depending on
|
jbe@0
|
414 whether this string occurred in the list of comma separated values of one
|
jbe@0
|
415 header line with the given field name that was the key in the first table.
|
jbe@0
|
416
|
jbe@0
|
417
|
jbe@0
|
418 ### request.headers_value
|
jbe@0
|
419
|
jbe@0
|
420 A table that maps (case-insensitively) a HTTP header field name to a value. If
|
jbe@0
|
421 multiple header lines with the given field name have been received, false is
|
jbe@0
|
422 used as value.
|
jbe@0
|
423
|
jbe@0
|
424
|
jbe@0
|
425 ### request.method
|
jbe@0
|
426
|
jbe@0
|
427 The HTTP request method, e.g. "HEAD", "GET", or "POST".
|
jbe@0
|
428
|
jbe@0
|
429
|
jbe@0
|
430 ### request.path
|
jbe@0
|
431
|
jbe@10
|
432 The requested path without a leading slash and without the query part (e.g.
|
jbe@10
|
433 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
|
jbe@10
|
434 see request.query.
|
jbe@10
|
435
|
jbe@10
|
436 This value will be nil if (and only if) the request method is "OPTIONS" with a
|
jbe@10
|
437 request target equal to "*" (see also asterisk-form of request-target in
|
jbe@10
|
438 section 5.3.4 in RFC 7230).
|
jbe@0
|
439
|
jbe@0
|
440
|
jbe@0
|
441 ### request.post_metadata
|
jbe@0
|
442
|
jbe@0
|
443 Only set for multipart/form-data POST requests. A table that maps field names
|
jbe@0
|
444 to their corresponding POST metadata table which contains two entries:
|
jbe@0
|
445 "file_name" and "content_type". If there are several POST values with the given
|
jbe@0
|
446 field name, then the first value/file is used.
|
jbe@0
|
447
|
jbe@0
|
448
|
jbe@0
|
449 ### request.post_metadata_list
|
jbe@0
|
450
|
jbe@0
|
451 Only set for multipart/form-data POST requests. A table that maps field names
|
jbe@0
|
452 to a sequence with their corresponding POST metadata tables. Needed if multiple
|
jbe@0
|
453 files are uploaded with the same field name.
|
jbe@0
|
454
|
jbe@0
|
455
|
jbe@0
|
456 ### request.post_params
|
jbe@0
|
457
|
jbe@0
|
458 A table that maps field names to their corresponding POST value. If there are
|
jbe@0
|
459 several POST values with the given field name, then the first value is used.
|
jbe@0
|
460
|
jbe@35
|
461 Note: May be implemented through metamethods, but does support iteration
|
jbe@35
|
462 through pairs(...).
|
jbe@35
|
463
|
jbe@0
|
464
|
jbe@0
|
465 ### request.post_params_list
|
jbe@0
|
466
|
jbe@0
|
467 A table that maps field names to a sequence of their corresponding POST values.
|
jbe@0
|
468
|
jbe@35
|
469 Note: May be implemented through metamethods, but does support iteration
|
jbe@35
|
470 through pairs(...).
|
jbe@35
|
471
|
jbe@0
|
472
|
jbe@0
|
473 ### request.query
|
jbe@0
|
474
|
jbe@12
|
475 Query part of the request target including the leading question mark, e.g.
|
jbe@12
|
476 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
|
jbe@10
|
477 automatically parsed and made available through request.get_params and
|
jbe@10
|
478 request.get_params_list.
|
jbe@10
|
479
|
jbe@10
|
480 If there is no query part given in the request target, then this string is
|
jbe@10
|
481 the empty string. This value will be nil if (and only if) the request method
|
jbe@10
|
482 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
|
jbe@10
|
483 request-target in section 5.3.4 in RFC 7230).
|
jbe@0
|
484
|
jbe@0
|
485
|
jbe@0
|
486 ### request:process_request_body()
|
jbe@0
|
487
|
jbe@0
|
488 Starts processing the request body (if existent) to set the values
|
jbe@0
|
489 request.post_params, request.post_params_list, request.post_metadata, and
|
jbe@0
|
490 and request.post_metadata_list and/or to call POST field stream handlers that
|
jbe@0
|
491 have been previously registered with request:stream_post_param(...) or
|
jbe@0
|
492 request:stream_post_params(...).
|
jbe@0
|
493
|
jbe@0
|
494 This method gets invoked automatically when the POST param tables
|
jbe@0
|
495 (request.post_params, etc.) are accessed, or if a response is sent (to avoid
|
jbe@0
|
496 deadlocks with the webbrowser). (Note: Automatic request body processing on
|
jbe@0
|
497 write may be disabled by calling request:defer_reading().)
|
jbe@0
|
498
|
jbe@0
|
499 After this method returned, all registered POST field stream handlers have
|
jbe@0
|
500 received all data. Registration of other POST field stream handlers is not
|
jbe@0
|
501 possible after this method has been called (or after request.post_params_list
|
jbe@0
|
502 or request.post_params have been accessed).
|
jbe@0
|
503
|
jbe@0
|
504
|
jbe@0
|
505 ### request:send_data(...)
|
jbe@0
|
506
|
jbe@0
|
507 Sends data as response body. All arguments are converted via tostring(...) and
|
jbe@0
|
508 concatenated. May be called multiple times until the request has been finished
|
jbe@0
|
509 by calling request:finish().
|
jbe@0
|
510
|
jbe@0
|
511 If the request method (see request.method) is "HEAD", then calls to
|
jbe@0
|
512 request:send_data(...) are automatically ignored.
|
jbe@0
|
513
|
jbe@0
|
514
|
jbe@0
|
515 ### request:send_header(key, value)
|
jbe@0
|
516
|
jbe@0
|
517 Sends a HTTP response header that consists of the given key and the given
|
jbe@0
|
518 value. Note: Key and value must be provided as separate arguments. Before any
|
jbe@0
|
519 headers can be sent, a HTTP status must have been set with
|
jbe@0
|
520 request:send_status(status_string).
|
jbe@0
|
521
|
jbe@0
|
522
|
jbe@0
|
523 ### request:send_status(status_string)
|
jbe@0
|
524
|
jbe@0
|
525 Sends a HTTP response status that is given as a string consisting of a 3-digit
|
jbe@0
|
526 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
|
jbe@0
|
527 function must be called once before any headers or response body data may be
|
jbe@0
|
528 sent.
|
jbe@0
|
529
|
jbe@0
|
530
|
jbe@0
|
531 ### request.socket
|
jbe@0
|
532
|
jbe@0
|
533 The underlaying socket. Can be used to force a TCP RST, etc.
|
jbe@0
|
534
|
jbe@0
|
535
|
jbe@0
|
536 ### request:stream_post_param(field_name, callback)
|
jbe@0
|
537
|
jbe@0
|
538 Registers a stream handler for the given POST parameter. The callback function
|
jbe@0
|
539 will be called in the following manner:
|
jbe@0
|
540
|
jbe@0
|
541 - For the initial chunk, the first chunk gets passed as first argument while a
|
jbe@0
|
542 table with metadata ("field_name" and "content_type") gets passed as second
|
jbe@0
|
543 argument. In case of an immediate EOF (i.e. an empty file), the passed
|
jbe@0
|
544 chunk is the empty string. In all other cases the chunk has a length greater
|
jbe@0
|
545 than zero.
|
jbe@0
|
546 - For any remaining chunks, the respective chunk gets passed as first and only
|
jbe@0
|
547 argument (no metadata). Here, the chunk has always a length greater than
|
jbe@0
|
548 zero.
|
jbe@0
|
549 - To indicate the end of the stream, the callback function is called without
|
jbe@0
|
550 arguments. This also happens in case of an immediate EOF (see above).
|
jbe@0
|
551
|
jbe@0
|
552 In case of an immediate EOF (i.e. an empty file), the callback function is thus
|
jbe@0
|
553 called as follows:
|
jbe@0
|
554
|
jbe@0
|
555 - The first time with an empty string as first argument, and with the metadata
|
jbe@0
|
556 as second argument.
|
jbe@0
|
557 - The second time without any arguments.
|
jbe@0
|
558
|
jbe@0
|
559
|
jbe@0
|
560 ### request:stream_post_params(pattern, callback)
|
jbe@0
|
561
|
jbe@0
|
562 Same as request:stream_post_param(...) but providing a string pattern to match
|
jbe@0
|
563 multiple field names (e.g. "^file_[0-9]+$").
|
jbe@0
|
564
|
jbe@0
|
565
|
jbe@0
|
566 ### request:stream_request_body(callback)
|
jbe@0
|
567
|
jbe@0
|
568 Start streaming of request body. For each chunk of the request body, the
|
jbe@0
|
569 callback function is called with the corresponding chunk. End of data is
|
jbe@0
|
570 indicated through return of request:stream_request_body(...) (not by calling
|
jbe@0
|
571 the callback without arguments).
|
jbe@0
|
572
|
jbe@44
|
573 The function may be called with nil instead of a callback function. In this
|
jbe@44
|
574 case, the request body is read and discarded. Only if nil is passed instead of
|
jbe@44
|
575 a callback, then the function may also be invoked when the request body has
|
jbe@44
|
576 already been read and/or processed. In the latter case, the function performs
|
jbe@44
|
577 no operation.
|
jbe@0
|
578
|
jbe@44
|
579
|