From a3270c17abb3f8070bfa4fde5513d92e4a8510fd Mon Sep 17 00:00:00 2001 From: Andrew Lewis Date: Fri, 23 Feb 2018 15:32:17 +0200 Subject: [PATCH] [Minor] Start of documentation for Lua API in Lua --- doc/Makefile | 102 ++++++++++++++++++++++----------------- doc/doxydown/doxydown.pl | 2 +- lualib/lua_maps.lua | 28 +++++++++++ lualib/lua_redis.lua | 37 ++++++++++++++ lualib/lua_util.lua | 56 +++++++++++++++++++++ 5 files changed, 180 insertions(+), 45 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 0f1b728cc..a6c6e1665 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,6 +2,7 @@ PANDOC ?= pandoc LUADOC ?= doxydown/doxydown.pl +LLUADOC ?= ${LUADOC} -l lua -e lua all: man @@ -14,49 +15,62 @@ rspamc.1: rspamc.1.md rspamadm.1: rspamadm.1.md $(PANDOC) -s -f markdown -t man -o rspamadm.1 rspamadm.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_tcp lua_mempool lua_html lua_util lua_fann lua_sqlite3 lua_cryptobox - -lua_regexp: ../src/lua/lua_regexp.c - $(LUADOC) < ../src/lua/lua_regexp.c > markdown/lua/regexp.md -lua_ip: ../src/lua/lua_ip.c - $(LUADOC) < ../src/lua/lua_ip.c > markdown/lua/ip.md -lua_config: ../src/lua/lua_config.c - $(LUADOC) < ../src/lua/lua_config.c > markdown/lua/config.md -lua_task: ../src/lua/lua_task.c +lua-dirs: + mkdir -p markdown/lua + +lua-doc: lua-dirs rspamd_regexp rspamd_ip rspamd_config task ucl rspamd_http rspamd_trie \ + rspamd_resolver rspamd_redis rspamd_upstream_list rspamd_expression rspamd_mimepart rspamd_logger rspamd_url \ + rspamd_tcp rspamd_mempool rspamd_html rspamd_util rspamd_fann rspamd_sqlite3 rspamd_cryptobox \ + lua_redis lua_util lua_maps + +lua_redis: + $(LLUADOC) < ../lualib/lua_redis.lua > markdown/lua/lua_redis.md + +lua_util: + $(LLUADOC) < ../lualib/lua_util.lua > markdown/lua/lua_util.md + +lua_maps: + $(LLUADOC) < ../lualib/lua_maps.lua > markdown/lua/lua_maps.md + +rspamd_regexp: ../src/lua/lua_regexp.c + $(LUADOC) < ../src/lua/lua_regexp.c > markdown/lua/rspamd_regexp.md +rspamd_ip: ../src/lua/lua_ip.c + $(LUADOC) < ../src/lua/lua_ip.c > markdown/lua/rspamd_ip.md +rspamd_config: ../src/lua/lua_config.c + $(LUADOC) < ../src/lua/lua_config.c > markdown/lua/rspamd_config.md +task: ../src/lua/lua_task.c $(LUADOC) < ../src/lua/lua_task.c > markdown/lua/task.md -lua_ucl: ../contrib/libucl/lua_ucl.c +ucl: ../contrib/libucl/lua_ucl.c $(LUADOC) < ../contrib/libucl/lua_ucl.c > markdown/lua/ucl.md -lua_http: ../src/lua/lua_http.c - $(LUADOC) < ../src/lua/lua_http.c > markdown/lua/http.md -lua_trie: ../src/lua/lua_trie.c - $(LUADOC) < ../src/lua/lua_trie.c > markdown/lua/trie.md -lua_dns: ../src/lua/lua_dns.c - $(LUADOC) < ../src/lua/lua_dns.c > markdown/lua/dns.md -lua_redis: ../src/lua/lua_redis.c - $(LUADOC) < ../src/lua/lua_redis.c > markdown/lua/redis.md -lua_upstream: ../src/lua/lua_upstream.c - $(LUADOC) < ../src/lua/lua_upstream.c > markdown/lua/upstream.md -lua_expression: ../src/lua/lua_expression.c - $(LUADOC) < ../src/lua/lua_expression.c > markdown/lua/expression.md -lua_mimepart: ../src/lua/lua_mimepart.c - $(LUADOC) < ../src/lua/lua_mimepart.c > markdown/lua/mimepart.md -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 -lua_tcp: ../src/lua/lua_tcp.c - $(LUADOC) < ../src/lua/lua_tcp.c > markdown/lua/tcp.md -lua_mempool: ../src/lua/lua_mempool.c - $(LUADOC) < ../src/lua/lua_mempool.c > markdown/lua/mempool.md -lua_html: ../src/lua/lua_html.c - $(LUADOC) < ../src/lua/lua_html.c > markdown/lua/html.md -lua_util: ../src/lua/lua_util.c - $(LUADOC) < ../src/lua/lua_util.c > markdown/lua/util.md -lua_fann: ../src/lua/lua_fann.c - $(LUADOC) < ../src/lua/lua_fann.c > markdown/lua/fann.md -lua_sqlite3: ../src/lua/lua_sqlite3.c - $(LUADOC) < ../src/lua/lua_sqlite3.c > markdown/lua/sqlite3.md -lua_cryptobox: ../src/lua/lua_cryptobox.c - $(LUADOC) < ../src/lua/lua_cryptobox.c > markdown/lua/cryptobox.md \ No newline at end of file +rspamd_http: ../src/lua/lua_http.c + $(LUADOC) < ../src/lua/lua_http.c > markdown/lua/rspamd_http.md +rspamd_trie: ../src/lua/lua_trie.c + $(LUADOC) < ../src/lua/lua_trie.c > markdown/lua/rspamd_trie.md +rspamd_resolver: ../src/lua/lua_dns.c + $(LUADOC) < ../src/lua/lua_dns.c > markdown/lua/rspamd_resolver.md +rspamd_redis: ../src/lua/lua_redis.c + $(LUADOC) < ../src/lua/lua_redis.c > markdown/lua/rspamd_redis.md +rspamd_upstream_list: ../src/lua/lua_upstream.c + $(LUADOC) < ../src/lua/lua_upstream.c > markdown/lua/rspamd_upstream.md +rspamd_expression: ../src/lua/lua_expression.c + $(LUADOC) < ../src/lua/lua_expression.c > markdown/lua/rspamd_expression.md +rspamd_mimepart: ../src/lua/lua_mimepart.c + $(LUADOC) < ../src/lua/lua_mimepart.c > markdown/lua/rspamd_mimepart.md +rspamd_logger: ../src/lua/lua_logger.c + $(LUADOC) < ../src/lua/lua_logger.c > markdown/lua/rspamd_logger.md +rspamd_url: ../src/lua/lua_url.c + $(LUADOC) < ../src/lua/lua_url.c > markdown/lua/rspamd_url.md +rspamd_tcp: ../src/lua/lua_tcp.c + $(LUADOC) < ../src/lua/lua_tcp.c > markdown/lua/rspamd_tcp.md +rspamd_mempool: ../src/lua/lua_mempool.c + $(LUADOC) < ../src/lua/lua_mempool.c > markdown/lua/rspamd_mempool.md +rspamd_html: ../src/lua/lua_html.c + $(LUADOC) < ../src/lua/lua_html.c > markdown/lua/rspamd_html.md +rspamd_util: ../src/lua/lua_util.c + $(LUADOC) < ../src/lua/lua_util.c > markdown/lua/rspamd_util.md +rspamd_fann: ../src/lua/lua_fann.c + $(LUADOC) < ../src/lua/lua_fann.c > markdown/lua/rspamd_fann.md +rspamd_sqlite3: ../src/lua/lua_sqlite3.c + $(LUADOC) < ../src/lua/lua_sqlite3.c > markdown/lua/rspamd_sqlite3.md +rspamd_cryptobox: ../src/lua/lua_cryptobox.c + $(LUADOC) < ../src/lua/lua_cryptobox.c > markdown/lua/rspamd_cryptobox.md diff --git a/doc/doxydown/doxydown.pl b/doc/doxydown/doxydown.pl index 45a11ba13..d58d4a906 100755 --- a/doc/doxydown/doxydown.pl +++ b/doc/doxydown/doxydown.pl @@ -19,7 +19,7 @@ my %languages = ( filter => qr/^(?:\s*\*+\s*)?(\s*\S.+)\s*$/, }, lua => { - start => qr/^\s*\--(?:\[\[+|-+)\s*$/, + start => qr/^\s*\--(?:\[\[\[+|-+)\s*$/, end => qr/^\s*--(:?\]\]+|-+)\s*$/, filter => qr/^(?:\s*--!?\s)?(\s*\S.+)\s*$/, }, diff --git a/lualib/lua_maps.lua b/lualib/lua_maps.lua index 7b48db034..41ab2552c 100644 --- a/lualib/lua_maps.lua +++ b/lualib/lua_maps.lua @@ -1,3 +1,8 @@ +--[[[ +-- @module lua_maps +-- This module contains helper functions for managing rspamd maps +--]] + --[[ Copyright (c) 2017, Vsevolod Stakhov @@ -16,6 +21,16 @@ limitations under the License. local exports = {} +--[[[ +-- @function lua_maps.map_add_from_ucl(opt, mtype, description) +-- Creates a map from static data +-- Returns true if map was added or nil +-- @param {string or table} opt data for map (or URL) +-- @param {string} mtype type of map (`set`, `map`, `radix`, `regexp`) +-- @param {string} description human-readable description of map +-- @return {bool} true on success, or `nil` +--]] + local function rspamd_map_add_from_ucl(opt, mtype, description) local ret = { get_key = function(t, k) @@ -144,6 +159,17 @@ local function rspamd_map_add_from_ucl(opt, mtype, description) return nil end +--[[[ +-- @function lua_maps.map_add(mname, optname, mtype, description) +-- Creates a map from configuration elements (static data or URL) +-- Returns true if map was added or nil +-- @param {string} mname config section to use +-- @param {string} optname option name to use +-- @param {string} mtype type of map ('set', 'hash', 'radix', 'regexp') +-- @param {string} description human-readable description of map +-- @return {bool} true on success, or `nil` +--]] + local function rspamd_map_add(mname, optname, mtype, description) local opt = rspamd_config:get_module_opt(mname, optname) @@ -151,7 +177,9 @@ local function rspamd_map_add(mname, optname, mtype, description) end exports.rspamd_map_add = rspamd_map_add +exports.map_add = rspamd_map_add exports.rspamd_map_add_from_ucl = rspamd_map_add_from_ucl +exports.map_add_from_ucl = rspamd_map_add_from_ucl -- Check `what` for being lua_map name, otherwise just compares key with what local function rspamd_maybe_check_map(key, what) diff --git a/lualib/lua_redis.lua b/lualib/lua_redis.lua index 2102db841..2fb7c3781 100644 --- a/lualib/lua_redis.lua +++ b/lualib/lua_redis.lua @@ -22,6 +22,11 @@ local exports = {} local E = {} +--[[[ +-- @module lua_redis +-- This module contains helper functions for working with Redis +--]] + local function try_load_redis_servers(options, rspamd_config, result) local default_port = 6379 local default_timeout = 1.0 @@ -185,6 +190,20 @@ local function rspamd_parse_redis_server(module_name, module_opts, no_fallback) end end +--[[[ +-- @function lua_redis.parse_redis_server(module_name, module_opts, no_fallback) +-- Extracts Redis server settings from configuration +-- @param {string} module_name name of module to get settings for +-- @param {table} module_opts settings for module or `nil` to fetch them from configuration +-- @param {boolean} no_fallback should be `true` if global settings must not be used +-- @return {table} redis server settings +-- @example +-- local rconfig = lua_redis.parse_redis_server('my_module') +-- -- rconfig contains upstream_list objects in ['write_servers'] and ['read_servers'] +-- -- ['timeout'] contains timeout in seconds +-- -- ['expand_keys'] if true tells that redis key expansion is enabled +--]] + exports.rspamd_parse_redis_server = rspamd_parse_redis_server exports.parse_redis_server = rspamd_parse_redis_server @@ -567,6 +586,18 @@ local function rspamd_redis_make_request(task, redis_params, key, is_write, return ret,conn,addr end +--[[[ +-- @function lua_redis.redis_make_request(task, redis_params, key, is_write, callback, command, args) +-- Sends a request to Redis +-- @param {rspamd_task} task task object +-- @param {table} redis_params redis configuration in format returned by lua_redis.parse_redis_server() +-- @param {string} key key to use for sharding +-- @param {boolean} is_write should be `true` if we are performing a write operating +-- @param {function} callback callback function (first parameter is error if applicable, second is a 2D array (table)) +-- @param {string} command Redis command to run +-- @param {table} args Numerically indexed table containing arguments for command +--]] + exports.rspamd_redis_make_request = rspamd_redis_make_request exports.redis_make_request = rspamd_redis_make_request @@ -639,6 +670,12 @@ local function redis_make_request_taskless(ev_base, cfg, redis_params, key, return ret,conn,addr end +--[[[ +-- @function lua_redis.redis_make_request_taskless(ev_base, redis_params, key, is_write, callback, command, args) +-- Sends a request to Redis in context where `task` is not available for some specific use-cases +-- Identical to redis_make_request() except in that first parameter is an `event base` object +--]] + exports.rspamd_redis_make_request_taskless = redis_make_request_taskless exports.redis_make_request_taskless = redis_make_request_taskless diff --git a/lualib/lua_util.lua b/lualib/lua_util.lua index f7e92937d..54b6c1d5e 100644 --- a/lualib/lua_util.lua +++ b/lualib/lua_util.lua @@ -14,6 +14,11 @@ See the License for the specific language governing permissions and limitations under the License. ]]-- +--[[[ +-- @module lua_util +-- This module contains utility functions for working with Lua and/or Rspamd +--]] + local exports = {} local lpeg = require 'lpeg' @@ -32,7 +37,16 @@ local function rspamd_str_split(s, sep) return gr:match(s) end +--[[[ +-- @function lua_util.str_split(text, deliminator) +-- Splits text into a numeric table by deliminator +-- @param {string} text deliminated text +-- @param {string} deliminator the deliminator +-- @return {table} numeric table containing string parts +--]] + exports.rspamd_str_split = rspamd_str_split +exports.str_split = rspamd_str_split local space = lpeg.S' \t\n\v\f\r' local nospace = 1 - space @@ -42,12 +56,32 @@ exports.rspamd_str_trim = function(s) return match(ptrim, s) end +--[[[ +-- @function lua_util.round(number, decimalPlaces) +-- Round number to fixed number of decimal points +-- @param {number} number number to round +-- @param {number} decimalPlaces number of decimal points +-- @return {number} rounded number +--]] + -- Robert Jay Gould http://lua-users.org/wiki/SimpleRound exports.round = function(num, numDecimalPlaces) local mult = 10^(numDecimalPlaces or 0) return math.floor(num * mult) / mult end +--[[[ +-- @function lua_util.template(text, replacements) +-- Replaces values in a text template +-- Variable names can contain letters, numbers and underscores, are prefixed with `$` and may or not use curly braces. +-- @param {string} text text containing variables +-- @param {table} replacements key/value pairs for replacements +-- @return {string} string containing replaced values +-- @example +-- local goop = lua_util.template("HELLO $FOO ${BAR}!", {['FOO'] = 'LUA', ['BAR'] = 'WORLD'}) +-- -- goop contains "HELLO LUA WORLD!" +--]] + exports.template = function(tmpl, keys) local var_lit = lpeg.P { lpeg.R("az") + lpeg.R("AZ") + lpeg.R("09") + "_" } local var = lpeg.P { (lpeg.P("$") / "") * ((var_lit^1) / keys) } @@ -160,11 +194,26 @@ exports.is_rspamc_or_controller = function(task) return is_rspamc end +--[[[ +-- @function lua_util.unpack(table) +-- Converts numeric table to varargs +-- This is `unpack` on Lua 5.1/5.2/LuaJIT and `table.unpack` on Lua 5.3 +-- @param {table} table numerically indexed table to unpack +-- @return {varargs} unpacked table elements +--]] + local unpack_function = table.unpack or unpack exports.unpack = function(t) return unpack_function(t) end +--[[[ +-- @function lua_util.spairs(table) +-- Like `pairs` but keys are sorted lexicographically +-- @param {table} table table containing key/value pairs +-- @return {function} generator function returning key/value pairs +--]] + -- Sorted iteration: -- for k,v in spairs(t) do ... end -- @@ -199,6 +248,13 @@ end exports.spairs = spairs +--[[[ +-- @function lua_util.disable_module(modname, how) +-- Disables a plugin or disables redis for a plugin. +-- @param {string} modname name of plugin to disable +-- @param {string} how 'redis' to disable redis, 'config' to disable startup +--]] + local function disable_module(modname, how) if rspamd_plugins_state.enabled[modname] then rspamd_plugins_state.enabled[modname] = nil -- 2.39.5