From: Vsevolod Stakhov <vsevolod@highsecure.ru>
Date: Tue, 19 May 2015 17:38:09 +0000 (+0100)
Subject: Add documentation for lua_tcp.
X-Git-Tag: 0.9.4~22
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=fb423e20ebef28cc169f50973e83f75506ed5527;p=rspamd.git

Add documentation for lua_tcp.
---

diff --git a/doc/Makefile b/doc/Makefile
index 1106e7bb2..86f9318ca 100644
--- 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 2139a9d41..9d204daa8 100644
--- 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)
 {