moonbridge
view reference.txt @ 334:62901393deb0
Updated reference regarding dual IPv6/IPv4 sockets
author | jbe |
---|---|
date | Wed Apr 28 13:03:13 2021 +0200 (2021-04-28) |
parents | 15132b3c053d |
children |
line source
2 Moonbridge reference
3 ====================
7 Global function listen{...}
8 ---------------------------
10 This function initializes the Moonbridge Network Server. It may be called
11 multiple times. However, it is not allowed to register additional listeners by
12 calling listen{...} from a "prepare", "connect", or "finish" handler.
14 See file "example.lua" for parametrization of the listen{...} function.
16 Warning: Moonbridge will fork the Lua environment to handle parallel requests.
17 Functions provided as "prepare", "connect", and "finish" handlers may access
18 global variables, but for every child process these global variables will not
19 be shared! If you require a global state, a DBMS, cache server, or similar is
20 necessary.
24 Global function timeout(...)
25 ----------------------------
27 Calling this function with a positive number (time in seconds) sets a timer
28 that kills the current process after the selected time runs out. The remaining
29 time can be queried by calling this function without arguments.
31 Calling this function with a single argument that is the number zero will
32 disable the timeout.
34 Another mode of operation is selected by passing two arguments: a time (in
35 seconds) as first argument and a function as second argument. In this case, a
36 sub-timer will be used to limit the execution time of the function. In case of
37 timeout, the process will be killed (and the timeout function does not return).
38 If the time for the sub-timer is longer than a previously set timeout (using
39 the timeout(...) function with one argument), the shorter timeout (of the
40 previous call of timeout(...)) will have precedence.
42 Timers are also automatically reset (disabled) when a handler (prepare handler
43 or connect handler) returns. To shutdown processes after a certain time waiting
44 for a new request, use the idle_time parameter of the listen function.
48 Socket object passed to "connect" handler
49 -----------------------------------------
51 For every incoming connection, the registered "connect" handler is called with
52 a single socket object as argument, which is described below:
55 ### socket:close()
57 Closes the socket connection (input and output stream) by flushing all data and
58 sending a TCP FIN packet.
60 Returns true on success, or nil plus error message in case of an I/O error.
61 Using this method on sockets that have already been closed (or reset) will
62 throw an error.
64 Warning: Pending data on the input stream may cause connection aborts (TCP RST)
65 when network connections are used. All pending input data should have been read
66 (or drained) before calling socket:close(). Use socket:finish() to send a
67 TCP FIN packet to the peer before waiting for EOF from the peer.
69 A socket passed to the "connect" handler will be closed automatically if it was
70 not closed by the "connect" handler and if the "connect" handler returns
71 normally (i.e. without throwing an error). If the "connect" handler throws an
72 error, then the socket will be reset. See socket:reset().
75 ### socket:drain(maxlen, terminator)
77 Same as socket:read(maxlen, terminator), but discards the input and returns the
78 number of discarded bytes (as first return value) and the status code ("term",
79 "maxlen", "eof" as second return value).
81 In case of an I/O error, nil (as first return value) plus an error message (as
82 second return value) are returned.
85 ### socket:drain_call(waitfunc, maxlen, terminator)
87 Same as socket:drain(maxlen, terminator), but calls waitfunc(socket, "r", first
88 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
89 the reading is blocked.
92 ### socket:drain_nb(maxlen, terminator)
94 Same as socket:drain(maxlen, terminator), but non-blocking. The status code
95 (which is returned as second return value) may therefore be "term", "maxlen",
96 "eof", or "block".
98 In case of an I/O error, nil (as first return value) plus an error message (as
99 second return value) are returned.
102 ### socket:drain_yield(maxlen, terminator)
104 Alias for socket:drain_call(coroutine.yield, maxlen, terminator)
107 ### socket:finish()
109 Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
110 still possible. When there is no more input data to be read, the connection
111 should finally be closed with socket:close().
113 In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
114 the underlying socket and emulates EOF on subsequent reads. Also in this case,
115 the connection should be finally closed with socket:close().
118 ### socket:flush(...)
120 Same as socket:write(...) but additionally flushes the socket (i.e. all pending
121 data is passed to the operating system).
123 In case of an I/O error, nil (as first return value) plus an error message (as
124 second return value) are returned. On success, the socket userdata object is
125 returned.
128 ### socket:flush_call(waitfunc, ...)
130 Same as socket:flush(...), but calls waitfunc(socket, "w", first,
131 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
132 the writing is blocked.
135 ### socket:flush_nb(...)
137 Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
138 pending data is passed to the operating system). The total number of bytes that
139 could not be passed yet to the operating system is returned. Zero is returned
140 if all data could be flushed out.
142 In case of an I/O error, nil (as first return value) plus an error message (as
143 second return value) are returned.
146 ### socket:flush_yield(...)
148 Alias for socket:flush_call(coroutine.yield, ...)
151 ### socket.interval
153 Set to the name of an interval timer if the "connect" handler was called due to
154 an elapsed interval timer. Otherwise nil.
157 ### socket.local_ip4
159 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
160 string.
163 ### socket.local_ip6
165 Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
166 a string.
169 ### socket.local_tcpport
171 Local TCP port used for the connection.
174 ### socket:read(maxlen, terminator)
176 Reads up to maxlen bytes or until an optional termination character is
177 encountered (which is included in the result). The maxlen value may be nil, in
178 which case there is no limit on the number of bytes read.
180 In case of an I/O error, nil (as first return value) plus an error message (as
181 second return value) are returned.
183 In all other cases (including EOF), the following two values are returned:
185 - a string containing the bytes read (first return value, may be empty string)
186 - a status code equal to "term", "maxlen", or "eof" (second return value)
188 If an EOF is encountered before all data could be read, then "eof" is returned
189 as second return value. If maxlen bytes have been read and no termination
190 character has been read, then "maxlen" is returned as second return value. If
191 the termination character is the last character of the read string, the second
192 return value will be "term".
195 ### socket:read_call(waitfunc, maxlen, terminator)
197 Same as socket:read(maxlen, terminator), but calls waitfunc(socket, "r", first,
198 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
199 the reading is blocked.
202 ### socket:read_nb(maxlen, terminator)
204 Same as socket:read(maxlen, terminator), but does not block.
206 In case of an I/O error, nil (as first return value) plus an error message (as
207 second return value) are returned.
209 In all other cases (including EOF), the following two values are returned:
211 - a string containing the bytes read (first return value, may be empty string)
212 - a status code equal to "term", "maxlen", "eof", "block" (second return value)
214 The status code "block" as second return value is used if the function returned
215 prematurely because it would block otherwise. In this case, the first return
216 value is a string that contains the bytes that could be read without blocking.
219 ### socket:read_yield(maxlen, terminator)
221 Alias for socket:read_call(coroutine.yield, maxlen, terminator)
224 ### socket.remote_ip4
226 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
227 a string.
230 ### socket.remote_ip6
232 Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
233 a string.
236 ### socket.remote_tcpport
238 Remote TCP port used for the connection.
241 ### socket:reset()
243 Alias for socket:close(). Closes the socket connection by sending a TCP RST
244 packet if possible to indicate error condition. This is the default operation
245 when a socket handle gets garbage collected or the process is terminated
246 abnormally.
248 Returns true on success, or nil (as first return value) plus error message (as
249 second return value) in case of an I/O error. Using this method on sockets that
250 have already been closed (or reset) will throw an error.
252 Warning: Previously sent (and flushed) data may be lost during transmission.
255 ### socket:write(...)
257 Takes a variable number of strings and sends them to the peer. The operation is
258 buffered, so to actually send out the data, it is necessary to eventually call
259 socket:flush(), socket:finish(), or socket:close().
261 In case of an I/O error, nil (as first return value) plus an error message (as
262 second return value) are returned. On success, the socket userdata object is
263 returned.
266 ### socket:write_call(waitfunc, ...)
268 Same as socket:write(...), but calls waitfunc(socket, "w", first,
269 moonbridge_io) (in an infinite loop, first=true only on first call) as long as
270 the writing is blocked.
273 ### socket:write_nb(...)
275 Takes a variable number of strings and sends them to the peer. The operation is
276 buffered, so to actually send out the data, it is necessary to eventually call
277 socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
279 This function always returns immediately (i.e. it does not block). If all data
280 (but a small buffered portion) could be sent out, then zero is returned.
281 Otherwise, all arguments that could not be sent are stored in a buffer of
282 unlimited size (up to memory capabilities) and an integer is returned that
283 indicates the number of bytes currently in the buffer.
285 In case of an I/O error, nil (as first return value) plus an error message (as
286 second return value) are returned.
289 ### socket:write_yield(...)
291 Alias for socket:write_call(coroutine.yield, ...)
295 I/O library
296 -----------
298 The Moonbridge Network Server for Lua Applications comes with its own I/O
299 library to support blocking as well as nonblocking I/O operations.
301 All methods on an I/O handle (e.g. socket) are described in the previous
302 section regarding the "socket" object. All other functions of the library are
303 listed below.
306 ### moonbridge_io.catch_sigterm()
308 This function installs a signal handler for SIGTERM. Instead of causing
309 immediate process termination, the behavior of moonbridge_io.poll(...) is
310 modified.
312 See moonbridge_io.poll(...) for further information.
315 ### moonbridge_io.exec(command, arg1, arg2, ...)
317 Executes the given command and returns a child handle with three sockets named
318 "stdin", "stdout", and "stderr" as well as the following methods:
320 - :kill(signal)
321 - :wait()
322 - :wait_nb()
323 - :wait_call(waitfunc)
324 - :wait_yield()
326 Use :kill(signal) to terminate the process with the given signal (defaults to 9
327 for SIGKILL).
329 The :wait() method will wait for the process to terminate and return its exit
330 code. If the process was terminated by a signal, a negative integer is returned
331 which corresponds to the respective positive signal number.
333 The method :wait_nb() is the same as :wait(), except that it does not block but
334 returns false (plus a notice as second return value) if the child process has
335 not terminated yet.
337 The method :wait_call() is the same as :wait() but calls waitfunc(child_handle,
338 "r", first, moonbridge_io) (in an infinite loop, first=true only on first call)
339 as long as the process is still running.
341 The method :wait_yield() is an alias for :wait_call(coroutine.yield).
343 It is possible to wait for process termination by including the child handle
344 in the input_set of the moonbridge_io.poll(...) call.
346 moonbridge_io.exec(...) returns nil (as first return value) plus an error
347 message (as second return value) in case of error.
350 ### moonbridge_io.getpid()
352 Returns the current PID.
355 ### moonbridge_io.localconnect(path)
357 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
358 a socket object on success, or nil (as first return value) plus an error
359 message (as second return value) in case of error.
362 ### moonbridge_io.localconnect_nb(path)
364 Tries to connect to a local socket (also known as Unix Domain Socket). Returns
365 a socket object on success, or nil (as first return value) plus an error
366 message (as second return value) in case of error.
368 Same as moonbridge_io.localconnect(path), except that this function does not
369 block and immediately returns a socket object.
371 In case of an I/O error, nil (as first return value) plus an error message (as
372 second return value) may be returned. However, connection errors may also be
373 reported on first read or write on the socket.
376 ### moonbridge_io.locallisten(path)
378 Attempts to create a local socket (also known as Unix Domain Socket) to accept
379 incoming connections. If the file does already exist and is a socket, then it
380 is deleted automatically before being re-created.
382 In case of an I/O error, nil (as first return value) plus an error message (as
383 second return value) may be returned. On success, a listener object is returned
384 which supports the methods :accept(), :accept_nb(), and :close().
386 The method :accept() blocks until a new incoming connection is available, in
387 which case a socket object is returned.
389 The method :accept_nb() works like :accept(), except that the call is
390 nonblocking and returns false (plus a notice as second return value) in case no
391 incoming connection is available. It is possible to wait for an incoming
392 connection by including the listener object in the input_set of the
393 moonbridge_io.poll(...) call.
395 The method :close() will close the listening socket. In case of local sockets
396 (Unix Domain Sockets), the socket will not be unlinked in the file system.
398 I/O errors by the methods of the listener object are also reported by returning
399 nil (as first return value) plus an error message (as second return value).
402 ### moonbridge_io.poll(input_set, output_set, timeout, wakeup_on_sigterm)
404 This function waits for at least one of the given file descriptors and/or
405 I/O handles to be ready for input or output. The two sets of file descriptors
406 and/or handles must contain the file descriptor or handle as a key, and a value
407 which does evaluate to true, e.g. input_set = {[socketA] = true}. If a set is
408 nil, it is treated as being empty.
410 The input_set may also contain listeners (to wait for incoming connections) and
411 child handles (to wait for process termination).
413 If the 4th parameter (wakeup_on_sigterm) is set to true, then the function
414 returns immediately if the process received at least one SIGTERM signal after
415 moonbridge_io.catch_sigterm() has been called for the first time. Three values
416 are returned if a timeout happened or a SIGTERM has been received: false as
417 first return value, a message string as second return value (that may, for
418 example, be used for assert(...)), and a boolean as third return value which
419 indicates whether the function prematurely returned because of SIGTERM.
421 If the 4th parameter (wakeup_on_sigterm) is omitted or set to false, then the
422 function only returns false as first return value if a timeout happened. In
423 this case, the second return value also will be set to an appropriate message
424 string such that assert(moonbridge_io.poll(...)) can be used to throw an error.
426 In all other cases, the function returns true as a single return value. The
427 function may also return true (for technical reasons) if signals other than
428 SIGTERM have been received during waiting.
430 Note that the function is not thread-safe when the 4th parameter is set to
431 true.
434 ### moonbridge_io.tcpconnect(hostname, port)
436 Tries to open a TCP connection with the given host and TCP port number. Returns
437 a socket object on success, or nil (as first return value) plus an error
438 message (as second return value) in case of error.
441 ### moonbridge_io.tcpconnect_nb(hostname, port)
443 Same as moonbridge_io.tcpconnect(hostname, port), except that this function
444 does not block and immediately returns a socket object.
446 Note: The current implementation still blocks during the DNS lookup. Use a
447 numeric IP address as hostname to be truly nonblocking.
449 In case of an I/O error, nil (as first return value) plus an error message (as
450 second return value) may be returned. However, connection errors may also be
451 reported on first read or write on the socket.
454 ### moonbridge_io.tcplisten(hostname, port)
456 Attempts to open a TCP port for listening. To listen on the loopback interface,
457 use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
458 IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
459 "0.0.0.0" (IPv4) respectively. When specifying nil as hostname, then both IPv6 and IPv4 are used on the same socket.
461 In case of an I/O error, nil (as first return value) plus an error message (as
462 second return value) may be returned. On success, a listener object is returned
463 which supports the methods :accept(), :accept_nb(), and :close(). See reference
464 for moonbridge.io_locallisten(...).
467 ### moonbridge_io.timeref(previous)
469 Helper function which returns a time reference (in SI-seconds). If a value is
470 passed as an optional argument to the function, then that value is substracted
471 from the result. A common idiom is:
473 local starttime = moonbridge_io.timeref()
474 [...]
475 while true do
476 [...]
477 if not moonbridge_io.poll(
478 input_set,
479 output_set,
480 timeout - moonbridge_io.timeref(starttime)
481 ) then
482 error("Timeout")
483 end
484 [...]
485 end
489 HTTP module
490 -----------
492 The HTTP module exports the function moonbridge_http.generate_handler(callback)
493 that converts an HTTP handler to a "connect" handler. See file "helloworld.lua"
494 for a simple example or "example_application.lua" for a more complex example of
495 invocation. A table with options may be passed either as a second argument, or
496 as a first argument preceeding the callback function (whichever is more
497 convenient).
499 The following options are supported:
501 - request_body_size_limit: maximum size of payload of HTTP request body
502 (transfer encoding is allowed to add a limited amount of extra data)
503 - chunk_size: optional default value for maximum_input_chunk_size and
504 minimum_output_chunk_size
505 - request_header_size_limit: maximum size of HTTP request headers
506 - maximum_input_chunk_size: maximum chunk size when streaming a request body or
507 certain POST fields (bigger chunks will be fragmented automatically)
508 - minimum_output_chunk_size: minimum size for a chunk when sending a response
509 body (smaller chunks will be buffered and concatenated with future data;
510 ignored when request:flush() is called)
511 - static_headers: a set of headers to be included in every HTTP response
512 (may be a string, a table or strings, or a table of key-value pairs)
514 The callback function receives a single request object as argument, which is
515 described below.
518 ### request.body
520 The request body (without headers) as a string. Accessing this value makes
521 further access to request.post_params and request.post_params_list, or
522 invocation of request:stream_request_body(...) impossible.
525 ### request:close_after_finish()
527 Closes the connection after answering the request.
529 This method can only be called before the HTTP response header section has been
530 finished (i.e. before request:finish_headers(), request:send_data(...), or
531 request:finish() were called), but it may be called before a status code has
532 been sent using request:send_status(...).
534 A corresponding "Connection: close" header is automatically sent.
536 See also request:monologue().
539 ### request:consume_input()
541 Starts processing the request body (if existent) to set the values
542 request.post_params, request.post_params_list, request.post_metadata, and
543 and request.post_metadata_list and/or to call POST field stream handlers that
544 have been previously registered with request:stream_post_param(...) or
545 request:stream_post_params(...), or to call a previously registered request
546 body stream handler that was set with request:set_request_body_streamer().
548 This method gets invoked automatically when the POST param tables
549 (request.post_params, etc.) are accessed or if request.body is accessed.
552 ### request.cookies
554 A table with all cookies sent by the client.
557 ### request.faulty
559 Normally set to false. In case of a write error on the client connection or
560 certain other unexpected errors, this value is set to true before a Lua error
561 is raised.
563 A faulty request handle must not be used, or another Lua error will be raised.
566 ### request:finish()
568 Finishes and flushes a HTTP response. An HTTP status, all headers, and the
569 response body (if applicable) must have been previously sent. May be called
570 multiple times (performs no operation if called on a finished request handle).
571 Gets automatically invoked when the callback handler returns. After calling
572 this method explicitly, no further data may be written.
575 ### request:finish_headers()
577 Finishes and flushes the HTTP response header section. May be called multiple
578 times, as long as the request is not finished completely. This method is
579 automatically invoked if the application is beginning to send a response body.
580 After calling this method, no further headers may be sent.
583 ### request:flush()
585 Flushes any pending output data. Note: In order to mark the end of a response
586 body, it is required to call request:finish().
589 ### request.fresh
591 Set to false whenever the request object has been used (e.g. data has been read
592 or sent out, or a stream handler was installed); true otherwise.
595 ### request.get_params
597 A table that maps field names to their corresponding GET value. If there are
598 several GET values with the given field name, then the first value is used.
600 Note: May be implemented through metamethods, but does support iteration
601 through pairs(...).
604 ### request.get_params_list
606 A table that maps field names to a sequence of their corresponding GET values.
608 Note: May be implemented through metamethods, but does support iteration
609 through pairs(...).
612 ### request.headers
614 A table that maps (case-insensitively) a HTTP header field name to a sequence
615 of values. For each occurrence of the respective header line, a string entry is
616 created in that sequence. Non-existent headers are mapped to an empty table.
619 ### request.headers_csv_string
621 A table that maps (case-insensitively) a HTTP header field name to a comma
622 separated string. Multiple occurrences of the header with the given field name
623 are automatically merged into the comma separated string.
626 ### request.headers_csv_table
628 A table that maps (case-insensitively) a HTTP header field name to a sequence
629 of values. One entry is created in that sequence for every comma separated
630 value of each header with the given field name.
633 ### request.headers_flags
635 A table that maps (case-insensitively) a HTTP header field name to another
636 table which (again case-insensitively) maps a string to a boolean, depending on
637 whether this string occurred in the list of comma separated values of one
638 header line with the given field name that was the key in the first table.
641 ### request.headers_value
643 A table that maps (case-insensitively) a HTTP header field name to a value. If
644 multiple header lines with the given field name have been received, false is
645 used as value.
648 ### request.method
650 The HTTP request method, e.g. "HEAD", "GET", or "POST".
653 ### request:monologue()
655 Same as request:close_after_finish() but additionally discards all input data
656 immediately.
659 ### request.path
661 The requested path without a leading slash and without the query part (e.g.
662 "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
663 see request.query.
665 This value will be nil if (and only if) the request method is "OPTIONS" with a
666 request target equal to "*" (see also asterisk-form of request-target in
667 section 5.3.4 in RFC 7230).
670 ### request.post_metadata
672 Only set for multipart/form-data POST requests. A table that maps field names
673 to their corresponding POST metadata table which contains two entries:
674 "file_name" and "content_type". If there are several POST values with the given
675 field name, then the first value/file is used.
677 Note: May be implemented through metamethods, but does support iteration
678 through pairs(...).
681 ### request.post_metadata_list
683 Only set for multipart/form-data POST requests. A table that maps field names
684 to a sequence with their corresponding POST metadata tables. Needed if multiple
685 files are uploaded with the same field name.
687 Note: May be implemented through metamethods, but does support iteration
688 through pairs(...).
691 ### request.post_params
693 A table that maps field names to their corresponding POST value. If there are
694 several POST values with the given field name, then the first value is used.
696 Note: May be implemented through metamethods, but does support iteration
697 through pairs(...).
700 ### request.post_params_list
702 A table that maps field names to a sequence of their corresponding POST values.
704 Note: May be implemented through metamethods, but does support iteration
705 through pairs(...).
708 ### request.query
710 Query part of the request target including the leading question mark, e.g.
711 "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
712 automatically parsed and made available through request.get_params and
713 request.get_params_list.
715 If there is no query part given in the request target, then this string is
716 the empty string. This value will be nil if (and only if) the request method
717 is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
718 request-target in section 5.3.4 in RFC 7230).
721 ### request:send_data(...)
723 Sends data as response body. All arguments are converted via tostring(...) and
724 concatenated. May be called multiple times until the request has been finished
725 by calling request:finish().
727 If the request method (see request.method) is "HEAD", then calls to
728 request:send_data(...) are automatically ignored.
731 ### request:send_header(key, value)
733 Sends a HTTP response header that consists of the given key and the given
734 value. Note: Key and value must be provided as separate arguments. Before any
735 headers can be sent, a HTTP status must have been set with
736 request:send_status(status_string).
739 ### request:send_status(status_string)
741 Sends a HTTP response status that is given as a string consisting of a 3-digit
742 number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
743 function must be called once before any headers or response body data may be
744 sent.
747 ### request.socket
749 The underlaying socket. Can be used to force a TCP RST, etc.
752 ### request:stream_post_param(field_name, callback)
754 Registers a stream handler for the given POST parameter. The callback function
755 will be called in the following manner:
757 - For the initial chunk, the first chunk gets passed as first argument while a
758 table with metadata ("field_name" and "content_type") gets passed as second
759 argument. In case of an immediate EOF (i.e. an empty file), the passed
760 chunk is the empty string. In all other cases the chunk has a length greater
761 than zero.
762 - For any remaining chunks, the respective chunk gets passed as first and only
763 argument (no metadata). Here, the chunk has always a length greater than
764 zero.
765 - To indicate the end of the stream, the callback function is called without
766 arguments. This also happens in case of an immediate EOF (see above).
768 In case of an immediate EOF (i.e. an empty file), the callback function is thus
769 called as follows:
771 - The first time with an empty string as first argument, and with the metadata
772 as second argument.
773 - The second time without any arguments.
775 Note that request:consume_input() needs to be called to enforce streaming to
776 finish.
779 ### request:stream_post_params(pattern, callback)
781 Same as request:stream_post_param(...) but providing a string pattern to match
782 multiple field names (e.g. "^file_[0-9]+$").
785 ### request:stream_request_body(callback)
787 Registeres a stream handler for the whole request body. For each chunk of the
788 request body, the callback function is called with the corresponding chunk. End
789 of data is indicated by passing a nil value to the callback functuion.
791 Note that request:consume_input() needs to be called to enforce streaming to
792 finish.
795 ### request:stream_request_body_now(callback)
797 Start streaming of request body immediately. On EOF the function returns and
798 the callback function is *not* called with nil as argument.