Add documentation for lua_tcp.

diff --git a/doc/Makefile b/doc/Makefile
index 1106e7bb25bb71fa65255d74a04928c43755ad9a..86f9318cac2687c38352c72d7a3b584f48c3ae00 100644 (file)
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -13,7 +13,8 @@ rspamc.1: rspamc.1.md
        $(PANDOC) -s -f markdown -t man -o rspamc.1 rspamc.1.md 
        
 lua-doc: lua_regexp lua_ip lua_config lua_task lua_ucl lua_http lua_trie \
-       lua_dns lua_redis lua_upstream lua_expression lua_mimepart lua_logger lua_url
+       lua_dns lua_redis lua_upstream lua_expression lua_mimepart lua_logger lua_url \
+       lua_tcp
 
 lua_regexp: ../src/lua/lua_regexp.c
        $(LUADOC) < ../src/lua/lua_regexp.c > markdown/lua/regexp.md
@@ -42,4 +43,6 @@ lua_mimepart: ../src/lua/lua_mimepart.c
 lua_logger: ../src/lua/lua_logger.c
        $(LUADOC) < ../src/lua/lua_logger.c > markdown/lua/logger.md
 lua_url: ../src/lua/lua_url.c
-       $(LUADOC) < ../src/lua/lua_url.c > markdown/lua/url.md
\ No newline at end of file
+       $(LUADOC) < ../src/lua/lua_url.c > markdown/lua/url.md
+lua_tcp: ../src/lua/lua_tcp.c
+       $(LUADOC) < ../src/lua/lua_tcp.c > markdown/lua/tcp.md
\ No newline at end of file

diff --git a/src/lua/lua_tcp.c b/src/lua/lua_tcp.c
index 2139a9d41681a7ca917bd5e5a75a9303bf886d87..9d204daa82116072264aab288904e8dec00d85f8 100644 (file)
--- a/src/lua/lua_tcp.c
+++ b/src/lua/lua_tcp.c
@@ -28,6 +28,32 @@
 #include "utlist.h"
 
 static void lua_tcp_handler (int fd, short what, gpointer ud);
+/***
+ * @module rspamd_tcp
+ * Rspamd TCP module represents generic TCP asynchronous client available from LUA code.
+ * This module hides all complexity: DNS resolving, sessions management, zero-copy
+ * text transfers and so on under the hood. It can work in partial or complete modes:
+ *
+ * - partial mode is used when you need to call a continuation routine each time data is available for read
+ * - complete mode calls for continuation merely when all data is read from socket (e.g. when a server sends reply and closes a connection)
+ * @example
+local logger = require "rspamd_logger"
+local tcp = require "rspamd_tcp"
+
+rspamd_config.SYM = function(task)
+
+    local function cb(err, data)
+        logger.infox('err: %1, data: %2', err, tostring(data))
+    end
+
+    tcp.request({
+       task = task,
+       host = "google.com",
+       port = 80,
+       data = {"GET / HTTP/1.0\r\n", "Host: google.com\r\n", "\r\n"},
+       callback = cb})
+end
+ */
 
 LUA_FUNCTION_DEF (tcp, request);
 
@@ -340,6 +366,26 @@ lua_tcp_arg_toiovec (lua_State *L, gint pos, rspamd_mempool_t *pool,
        return TRUE;
 }
 
+/***
+ * @function rspamd_tcp.request({params})
+ * This function creates and sends TCP request to the specified host and port,
+ * resolves hostname (if needed) and invokes continuation callback upon data received
+ * from the remote peer. This function accepts table of arguments with the following
+ * attributes
+ *
+ * - `task`: rspamd task objects (implies `pool`, `session`, `ev_base` and `resolver` arguments)
+ * - `ev_base`: event base (if no task specified)
+ * - `resolver`: DNS resolver (no task)
+ * - `session`: events session (no task)
+ * - `pool`: memory pool (no task)
+ * - `host`: IP or name of the peer (required)
+ * - `port`: remote port to use (required)
+ * - `data`: a table of strings or `rspamd_text` objects that contains data pieces
+ * - `callback`: continuation function (required)
+ * - `timeout`: floating point value that specifies timeout for IO operations in seconds
+ * - `partial`: boolean flag that specifies that callback should be called on any data portion received
+ * @return {boolean} true if request has been sent
+ */
 static gint
 lua_tcp_request (lua_State *L)
 {