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