PageRenderTime 60ms CodeModel.GetById 18ms RepoModel.GetById 1ms app.codeStats 0ms

/liquidfeedback/moonbridge/reference.txt

https://gitlab.com/fuzzynemesis/hajaannu
Plain Text | 736 lines | 449 code | 287 blank | 0 comment | 0 complexity | 70916a93c670884bee30ff9b86c8c45f MD5 | raw file
Possible License(s): Apache-2.0
  1. Moonbridge reference
  2. ====================
  3. Global function listen{...}
  4. ---------------------------
  5. This function initializes the Moonbridge Network Server. It may be called
  6. multiple times. However, it is not allowed to register additional listeners by
  7. calling listen(...) from a "prepare", "connect", or "finish" handler.
  8. See file "example.lua" for parametrization of the listen(...) function.
  9. Warning: Moonbridge will fork the Lua environment to handle parallel requests.
  10. Functions provided as "prepare", "connect", and "finish" handlers may access
  11. global variables, but for every child process these global variables will not
  12. be shared! If you require a global state, a DBMS, cache server, or similar is
  13. necessary.
  14. Global function timeout(...)
  15. ----------------------------
  16. Calling this function with a positive number (time in seconds) sets a timer
  17. that kills the current process after the selected time runs out. The remaining
  18. time can be queried by calling this function without arguments.
  19. Calling this function with a single argument that is the number zero will
  20. disable the timeout.
  21. Another mode of operation is selected by passing two arguments: a time (in
  22. seconds) as first argument and a function as second argument. In this case, a
  23. sub-timer will be used to limit the execution time of the function. In case of
  24. timeout, the process will be killed (and the timeout function does not return).
  25. If the time for the sub-timer is longer than a previously set timeout (using
  26. the timeout(...) function with one argument), the shorter timeout (of the
  27. previous call of timeout(...)) will have precedence.
  28. Timers are also automatically reset (disabled) when a handler (prepare handler
  29. or connect handler) returns. To shutdown processes after a certain time waiting
  30. for a new request, use the idle_time parameter of the listen function.
  31. Socket object passed to "connect" handler
  32. -----------------------------------------
  33. For every incoming connection, the registered "connect" handler is called with
  34. a single socket object as argument, which is described below:
  35. ### socket:close()
  36. Closes the socket connection (input and output stream) by flushing all data and
  37. sending a TCP FIN packet.
  38. Returns true on success, or nil plus error message in case of an I/O error.
  39. Using this method on sockets that have already been closed (or reset) will
  40. throw an error.
  41. Warning: Pending data on the input stream may cause connection aborts (TCP RST)
  42. when network connections are used. All pending input data should have been read
  43. (or drained) before calling socket:close(). Use socket:finish() to send a
  44. TCP FIN packet to the peer before waiting for EOF from the peer.
  45. A socket passed to the "connect" handler will be closed automatically if it was
  46. not closed by the "connect" handler and if the "connect" handler returns
  47. normally (i.e. without throwing an error). If the "connect" handler throws an
  48. error, then the socket will be reset. See socket:reset().
  49. ### socket:drain(maxlen, terminator)
  50. Same as socket:read(maxlen, terminator), but discards the input and returns the
  51. number of discarded bytes (as first return value) and the status code ("term",
  52. "maxlen", "eof" as second return value).
  53. In case of an I/O error, nil (as first return value) plus an error message (as
  54. second return value) are returned.
  55. ### socket:drain_call(waitfunc, maxlen, terminator)
  56. Same as socket:drain(maxlen, terminator), but calls waitfunc(socket, "r") (in
  57. an infinite loop) as long as the reading is blocked.
  58. ### socket:drain_nb(maxlen, terminator)
  59. Same as socket:drain(maxlen, terminator), but non-blocking. The status code
  60. (which is returned as second return value) may therefore be "term", "maxlen",
  61. "eof", or "block".
  62. In case of an I/O error, nil (as first return value) plus an error message (as
  63. second return value) are returned.
  64. ### socket:drain_yield(maxlen, terminator)
  65. Alias for socket:drain_call(coroutine.yield, maxlen, terminator)
  66. ### socket:finish()
  67. Sends a TCP FIN packet to indicate EOF on write stream. Subsequent reads are
  68. still possible. When there is no more input data to be read, the connection
  69. should finally be closed with socket:close().
  70. In case of local sockets (Unix Domain Sockets), socket:finish() simply closes
  71. the underlying socket and emulates EOF on subsequent reads. Also in this case,
  72. the connection should be finally closed with socket:close().
  73. ### socket:flush(...)
  74. Same as socket:write(...) but additionally flushes the socket (i.e. all pending
  75. data is passed to the operating system).
  76. In case of an I/O error, nil (as first return value) plus an error message (as
  77. second return value) are returned. On success, the socket userdata object is
  78. returned.
  79. ### socket:flush_call(waitfunc, ...)
  80. Same as socket:flush(...), but calls waitfunc() (in an infinite loop) as long
  81. as the writing is blocked.
  82. ### socket:flush_nb(...)
  83. Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
  84. pending data is passed to the operating system). The total number of bytes that
  85. could not be passed yet to the operating system is returned. Zero is returned
  86. if all data could be flushed out.
  87. In case of an I/O error, nil (as first return value) plus an error message (as
  88. second return value) are returned.
  89. ### socket:flush_yield(...)
  90. Alias for socket:flush_call(coroutine.yield, ...)
  91. ### socket.interval
  92. Set to the name of an interval timer if the "connect" handler was called due to
  93. an elapsed interval timer. Otherwise nil.
  94. ### socket.local_ip4
  95. Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
  96. string.
  97. ### socket.local_ip6
  98. Local IPv6 address used for the connection. Encoded as 16 raw bytes in form of
  99. a string.
  100. ### socket.local_tcpport
  101. Local TCP port used for the connection.
  102. ### socket:read(maxlen, terminator)
  103. Reads up to maxlen bytes or until an optional termination character is
  104. encountered (which is included in the result). The maxlen value may be nil, in
  105. which case there is no limit on the number of bytes read.
  106. In case of an I/O error, nil (as first return value) plus an error message (as
  107. second return value) are returned.
  108. In all other cases (including EOF), the following two values are returned:
  109. - a string containing the bytes read (first return value, may be empty string)
  110. - a status code equal to "term", "maxlen", or "eof" (second return value)
  111. If an EOF is encountered before all data could be read, then "eof" is returned
  112. as second return value. If maxlen bytes have been read and no termination
  113. character has been read, then "maxlen" is returned as second return value. If
  114. the termination character is the last character of the read string, the second
  115. return value will be "term".
  116. ### socket:read_call(waitfunc, maxlen, terminator)
  117. Same as socket:read(maxlen, terminator), but calls waitfunc() (in an infinite
  118. loop) as long as the reading is blocked.
  119. ### socket:read_nb(maxlen, terminator)
  120. Same as socket:read(maxlen, terminator), but does not block.
  121. In case of an I/O error, nil (as first return value) plus an error message (as
  122. second return value) are returned.
  123. In all other cases (including EOF), the following two values are returned:
  124. - a string containing the bytes read (first return value, may be empty string)
  125. - a status code equal to "term", "maxlen", "eof", "block" (second return value)
  126. The status code "block" as second return value is used if the function returned
  127. prematurely because it would block otherwise. In this case, the first return
  128. value is a string that contains the bytes that could be read without blocking.
  129. ### socket:read_yield(maxlen, terminator)
  130. Alias for socket:read_call(coroutine.yield, maxlen, terminator)
  131. ### socket.remote_ip4
  132. Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
  133. a string.
  134. ### socket.remote_ip6
  135. Remote IPv6 address used for the connection. Encoded as 16 raw bytes in form of
  136. a string.
  137. ### socket.remote_tcpport
  138. Remote TCP port used for the connection.
  139. ### socket:reset()
  140. Alias for socket:close(). Closes the socket connection by sending a TCP RST
  141. packet if possible to indicate error condition. This is the default operation
  142. when a socket handle gets garbage collected or the process is terminated
  143. abnormally.
  144. Returns true on success, or nil (as first return value) plus error message (as
  145. second return value) in case of an I/O error. Using this method on sockets that
  146. have already been closed (or reset) will throw an error.
  147. Warning: Previously sent (and flushed) data may be lost during transmission.
  148. ### socket:write(...)
  149. Takes a variable number of strings and sends them to the peer. The operation is
  150. buffered, so to actually send out the data, it is necessary to eventually call
  151. socket:flush(), socket:finish(), or socket:close().
  152. In case of an I/O error, nil (as first return value) plus an error message (as
  153. second return value) are returned. On success, the socket userdata object is
  154. returned.
  155. ### socket:write_call(waitfunc, ...)
  156. Same as socket:write(...), but calls waitfunc() (in an infinite loop) as long
  157. as the writing is blocked.
  158. ### socket:write_nb(...)
  159. Takes a variable number of strings and sends them to the peer. The operation is
  160. buffered, so to actually send out the data, it is necessary to eventually call
  161. socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
  162. This function always returns immediately (i.e. it does not block). If all data
  163. (but a small buffered portion) could be sent out, then zero is returned.
  164. Otherwise, all arguments that could not be sent are stored in a buffer of
  165. unlimited size (up to memory capabilities) and an integer is returned that
  166. indicates the number of bytes currently in the buffer.
  167. In case of an I/O error, nil (as first return value) plus an error message (as
  168. second return value) are returned.
  169. ### socket:write_yield(...)
  170. Alias for socket:write_call(coroutine.yield, ...)
  171. I/O library
  172. -----------
  173. The Moonbridge Network Server for Lua Applications comes with its own I/O
  174. library to support blocking as well as nonblocking I/O operations.
  175. All methods on an I/O handle (e.g. socket) are described in the previous
  176. section regarding the "socket" object. All other functions of the library are
  177. listed below.
  178. ### moonbridge_io.exec(command, arg1, arg2, ...)
  179. Executes the given command and returns a handle with three sockets named
  180. "stdin", "stdout", and "stderr" as well as the following methods:
  181. - :kill(signal)
  182. - :wait()
  183. - :wait_nb()
  184. - :wait_call(waitfunc)
  185. - :wait_yield()
  186. Use :kill(signal) to terminate the process with the given signal (defaults to
  187. 15 for SIGTERM).
  188. The :wait() method will wait for the process to terminate and return its exit
  189. code. If the process was terminated by a signal, a negative integer is returned
  190. which corresponds to the respective positive signal number.
  191. The method :wait_nb() is the same as :wait(), except that it does not block but
  192. returns false (plus a notice as second return value) if the child process has
  193. not terminated yet.
  194. The method :wait_call() is the same as :wait() but calls waitfunc() (in an
  195. infinite loop) as long as the process is still running.
  196. The method :wait_yield() is an alias for :wait_call(coroutine.yield).
  197. ### moonbridge_io.localconnect(path)
  198. Tries to connect to a local socket (also known as Unix Domain Socket). Returns
  199. a socket object on success, or nil (as first return value) plus an error
  200. message (as second return value) in case of error.
  201. ### moonbridge_io.localconnect_nb(path)
  202. Tries to connect to a local socket (also known as Unix Domain Socket). Returns
  203. a socket object on success, or nil (as first return value) plus an error
  204. message (as second return value) in case of error.
  205. Same as moonbridge_io.localconnect(path), except that this function does not
  206. block and immediately returns a socket object.
  207. In case of an I/O error, nil (as first return value) plus an error message (as
  208. second return value) may be returned. However, connection errors may also be
  209. reported on first read or write on the socket.
  210. ### moonbridge_io.locallisten(path)
  211. Attempts to create a local socket (also known as Unix Domain Socket) to accept
  212. incoming connections. If the file does already exist and is a socket, then it
  213. is deleted automatically before being re-created.
  214. In case of an I/O error, nil (as first return value) plus an error message (as
  215. second return value) may be returned. On success, a listener object is returned
  216. which supports the methods :accept(), :accept_nb(), and :close().
  217. The method :accept() blocks until a new incoming connection is available, in
  218. which case a socket object is returned.
  219. The method :accept_nb() works like :accept(), except that the call is
  220. nonblocking and returns false (plus a notice as second return value) in case no
  221. incoming connection is available. It is possible to wait for an incoming
  222. connection by including the listener object in the input_set of the
  223. moonbridge_io.poll(...) call.
  224. The method :close() will close the listening socket. In case of local sockets
  225. (Unix Domain Sockets), the socket will not be unlinked in the file system.
  226. I/O errors by the methods of the listener object are also reported by returning
  227. nil (as first return value) plus an error message (as second return value).
  228. ### moonbridge_io.poll(input_set, output_set, timeout)
  229. This function waits for at least one of the given file descriptors and/or
  230. I/O handles to be ready for input or output. The two sets of file descriptors
  231. and/or handles must contain the file descriptor or handle as a key, and a value
  232. which does evaluate to true, e.g. input_set = {[socketA] = true}. If a set is
  233. nil, it is treated as being empty.
  234. Returns true when at least one file descriptor or handle is ready for reading
  235. or writing respectively. Returns false (plus a notice as second return value)
  236. in case of timeout. Returns nil (plus a notice as second return value) if a
  237. signal was received during waiting.
  238. ### moonbridge_io.tcpconnect(hostname, port)
  239. Tries to open a TCP connection with the given host and TCP port number. Returns
  240. a socket object on success, or nil (as first return value) plus an error
  241. message (as second return value) in case of error.
  242. ### moonbridge_io.tcpconnect_nb(hostname, port)
  243. Same as moonbridge_io.tcpconnect(hostname, port), except that this function
  244. does not block and immediately returns a socket object.
  245. Note: The current implementation still blocks during the DNS lookup. Use a
  246. numeric IP address as hostname to be truly nonblocking.
  247. In case of an I/O error, nil (as first return value) plus an error message (as
  248. second return value) may be returned. However, connection errors may also be
  249. reported on first read or write on the socket.
  250. ### moonbridge_io.tcplisten(hostname, port)
  251. Attempts to open a TCP port for listening. To listen on the loopback interface,
  252. use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
  253. IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
  254. "0.0.0.0" (IPv4) respectively.
  255. In case of an I/O error, nil (as first return value) plus an error message (as
  256. second return value) may be returned. On success, a listener object is returned
  257. which supports the methods :accept(), :accept_nb(), and :close(). See reference
  258. for moonbridge.io_locallisten(...).
  259. HTTP module
  260. -----------
  261. The HTTP module exports the function moonbridge_http.generate_handler(callback)
  262. that converts an HTTP handler to a "connect" handler. See file "helloworld.lua"
  263. for a simple example or "example_application.lua" for a more complex example of
  264. invocation. A table with options may be passed either as a second argument, or
  265. as a first argument preceeding the callback function (whichever is more
  266. convenient).
  267. The following options are supported:
  268. - request_body_size_limit: maximum size of payload of HTTP request body
  269. (transfer encoding is allowed to add a limited amount of extra data)
  270. - chunk_size: optional default value for maximum_input_chunk_size and
  271. minimum_output_chunk_size
  272. - request_header_size_limit: maximum size of HTTP request headers
  273. - maximum_input_chunk_size: maximum chunk size when streaming a request body or
  274. certain POST fields (bigger chunks will be fragmented automatically)
  275. - minimum_output_chunk_size: minimum size for a chunk when sending a response
  276. body (smaller chunks will be buffered and concatenated with future data;
  277. ignored when request:flush() is called)
  278. - static_headers: a set of headers to be included in every HTTP response
  279. (may be a string, a table or strings, or a table of key-value pairs)
  280. The callback function receives a single request object as argument, which is
  281. described below.
  282. ### request.body
  283. The request body (without headers) as a string. Accessing this value makes
  284. further access to request.post_params and request.post_params_list, or
  285. invocation of request:stream_request_body(...) impossible.
  286. ### request:close_after_finish()
  287. Closes the connection after answering the request.
  288. This method can only be called before the HTTP response header section has been
  289. finished (i.e. before request:finish_headers(), request:send_data(...), or
  290. request:finish() were called), but it may be called before a status code has
  291. been sent using request:send_status(...).
  292. A corresponding "Connection: close" header is automatically sent.
  293. See also request:monologue().
  294. ### request:consume_input()
  295. Starts processing the request body (if existent) to set the values
  296. request.post_params, request.post_params_list, request.post_metadata, and
  297. and request.post_metadata_list and/or to call POST field stream handlers that
  298. have been previously registered with request:stream_post_param(...) or
  299. request:stream_post_params(...), or to call a previously registered request
  300. body stream handler that was set with request:set_request_body_streamer().
  301. This method gets invoked automatically when the POST param tables
  302. (request.post_params, etc.) are accessed or if request.body is accessed.
  303. ### request.cookies
  304. A table with all cookies sent by the client.
  305. ### request.faulty
  306. Normally set to false. In case of a write error on the client connection or
  307. certain other unexpected errors, this value is set to true before a Lua error
  308. is raised.
  309. A faulty request handle must not be used, or another Lua error will be raised.
  310. ### request:finish()
  311. Finishes and flushes a HTTP response. An HTTP status, all headers, and the
  312. response body (if applicable) must have been previously sent. May be called
  313. multiple times (performs no operation if called on a finished request handle).
  314. Gets automatically invoked when the callback handler returns. After calling
  315. this method explicitly, no further data may be written.
  316. ### request:finish_headers()
  317. Finishes and flushes the HTTP response header section. May be called multiple
  318. times, as long as the request is not finished completely. This method is
  319. automatically invoked if the application is beginning to send a response body.
  320. After calling this method, no further headers may be sent.
  321. ### request:flush()
  322. Flushes any pending output data. Note: In order to mark the end of a response
  323. body, it is required to call request:finish().
  324. ### request.fresh
  325. Set to false whenever the request object has been used (e.g. data has been read
  326. or sent out, or a stream handler was installed); true otherwise.
  327. ### request.get_params
  328. A table that maps field names to their corresponding GET value. If there are
  329. several GET values with the given field name, then the first value is used.
  330. Note: May be implemented through metamethods, but does support iteration
  331. through pairs(...).
  332. ### request.get_params_list
  333. A table that maps field names to a sequence of their corresponding GET values.
  334. Note: May be implemented through metamethods, but does support iteration
  335. through pairs(...).
  336. ### request.headers
  337. A table that maps (case-insensitively) a HTTP header field name to a sequence
  338. of values. For each occurrence of the respective header line, a string entry is
  339. created in that sequence. Non-existent headers are mapped to an empty table.
  340. ### request.headers_csv_string
  341. A table that maps (case-insensitively) a HTTP header field name to a comma
  342. separated string. Multiple occurrences of the header with the given field name
  343. are automatically merged into the comma separated string.
  344. ### request.headers_csv_table
  345. A table that maps (case-insensitively) a HTTP header field name to a sequence
  346. of values. One entry is created in that sequence for every comma separated
  347. value of each header with the given field name.
  348. ### request.headers_flags
  349. A table that maps (case-insensitively) a HTTP header field name to another
  350. table which (again case-insensitively) maps a string to a boolean, depending on
  351. whether this string occurred in the list of comma separated values of one
  352. header line with the given field name that was the key in the first table.
  353. ### request.headers_value
  354. A table that maps (case-insensitively) a HTTP header field name to a value. If
  355. multiple header lines with the given field name have been received, false is
  356. used as value.
  357. ### request.method
  358. The HTTP request method, e.g. "HEAD", "GET", or "POST".
  359. ### request:monologue()
  360. Same as request:close_after_finish() but additionally discards all input data
  361. immediately.
  362. ### request.path
  363. The requested path without a leading slash and without the query part (e.g.
  364. "index.html" if "/index.html?a=b&c=d" has been requested). For the query part,
  365. see request.query.
  366. This value will be nil if (and only if) the request method is "OPTIONS" with a
  367. request target equal to "*" (see also asterisk-form of request-target in
  368. section 5.3.4 in RFC 7230).
  369. ### request.post_metadata
  370. Only set for multipart/form-data POST requests. A table that maps field names
  371. to their corresponding POST metadata table which contains two entries:
  372. "file_name" and "content_type". If there are several POST values with the given
  373. field name, then the first value/file is used.
  374. Note: May be implemented through metamethods, but does support iteration
  375. through pairs(...).
  376. ### request.post_metadata_list
  377. Only set for multipart/form-data POST requests. A table that maps field names
  378. to a sequence with their corresponding POST metadata tables. Needed if multiple
  379. files are uploaded with the same field name.
  380. Note: May be implemented through metamethods, but does support iteration
  381. through pairs(...).
  382. ### request.post_params
  383. A table that maps field names to their corresponding POST value. If there are
  384. several POST values with the given field name, then the first value is used.
  385. Note: May be implemented through metamethods, but does support iteration
  386. through pairs(...).
  387. ### request.post_params_list
  388. A table that maps field names to a sequence of their corresponding POST values.
  389. Note: May be implemented through metamethods, but does support iteration
  390. through pairs(...).
  391. ### request.query
  392. Query part of the request target including the leading question mark, e.g.
  393. "?a=b&c=d" if the requested target is "/index.html?a=b&c=d". The data is
  394. automatically parsed and made available through request.get_params and
  395. request.get_params_list.
  396. If there is no query part given in the request target, then this string is
  397. the empty string. This value will be nil if (and only if) the request method
  398. is "OPTIONS" with a request target equal to "*" (see also asterisk-form of
  399. request-target in section 5.3.4 in RFC 7230).
  400. ### request:send_data(...)
  401. Sends data as response body. All arguments are converted via tostring(...) and
  402. concatenated. May be called multiple times until the request has been finished
  403. by calling request:finish().
  404. If the request method (see request.method) is "HEAD", then calls to
  405. request:send_data(...) are automatically ignored.
  406. ### request:send_header(key, value)
  407. Sends a HTTP response header that consists of the given key and the given
  408. value. Note: Key and value must be provided as separate arguments. Before any
  409. headers can be sent, a HTTP status must have been set with
  410. request:send_status(status_string).
  411. ### request:send_status(status_string)
  412. Sends a HTTP response status that is given as a string consisting of a 3-digit
  413. number and an explanatory string, e.g. "200 OK" or "404 Not Found". This
  414. function must be called once before any headers or response body data may be
  415. sent.
  416. ### request.socket
  417. The underlaying socket. Can be used to force a TCP RST, etc.
  418. ### request:stream_post_param(field_name, callback)
  419. Registers a stream handler for the given POST parameter. The callback function
  420. will be called in the following manner:
  421. - For the initial chunk, the first chunk gets passed as first argument while a
  422. table with metadata ("field_name" and "content_type") gets passed as second
  423. argument. In case of an immediate EOF (i.e. an empty file), the passed
  424. chunk is the empty string. In all other cases the chunk has a length greater
  425. than zero.
  426. - For any remaining chunks, the respective chunk gets passed as first and only
  427. argument (no metadata). Here, the chunk has always a length greater than
  428. zero.
  429. - To indicate the end of the stream, the callback function is called without
  430. arguments. This also happens in case of an immediate EOF (see above).
  431. In case of an immediate EOF (i.e. an empty file), the callback function is thus
  432. called as follows:
  433. - The first time with an empty string as first argument, and with the metadata
  434. as second argument.
  435. - The second time without any arguments.
  436. Note that request:consume_input() needs to be called to enforce streaming to
  437. finish.
  438. ### request:stream_post_params(pattern, callback)
  439. Same as request:stream_post_param(...) but providing a string pattern to match
  440. multiple field names (e.g. "^file_[0-9]+$").
  441. ### request:stream_request_body(callback)
  442. Registeres a stream handler for the whole request body. For each chunk of the
  443. request body, the callback function is called with the corresponding chunk. End
  444. of data is indicated by passing a nil value to the callback functuion.
  445. Note that request:consume_input() needs to be called to enforce streaming to
  446. finish.
  447. ### request:stream_request_body_now(callback)
  448. Start streaming of request body immediately. On EOF the function returns and
  449. the callback function is *not* called with nil as argument.