Module rspamd_http
Module rspamd_http
Rspamd HTTP module represents HTTP 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.
Example:
-- Basic GET request with callback
local rspamd_http = require "rspamd_http"
local function symbol_callback(task)
local function http_callback(err_message, code, body, headers)
task:insert_result('SYMBOL', 1) -- task is available via closure
if err_message then
-- Handle error
return
end
-- Process response
if code == 200 then
-- Process body and headers
for name, value in pairs(headers) do
-- Headers are lowercase
end
end
end
rspamd_http.request({
task=task,
url='http://example.com/data',
body=task:get_content(),
callback=http_callback,
headers={Header='Value', OtherHeader='Value', DuplicatedHeader={'Multiple', 'Values'}},
mime_type='text/plain',
})
end
-- POST request with JSON body
local function post_json_example(task)
local ucl = require "ucl"
local data = {
id = task:get_queue_id(),
sender = task:get_from()[1].addr
local json_data = ucl.to_json(data)
rspamd_http.request({
task = task,
url = "http://example.com/api/submit",
method = "POST",
body = json_data,
headers = {['Content-Type'] = 'application/json'},
callback = function(err, code, body, headers)
if not err and code == 200 then
-- Success
end
end
})
end
-- Synchronous HTTP request (using coroutines)
local function sync_http_example(task)
-- No callback makes this a synchronous call
local err, response = rspamd_http.request({
task = task,
url = "http://example.com/api/data",
method = "GET",
timeout = 10.0
})
if not err then
-- Response is a table with code, content, and headers
if response.code == 200 then
-- Process response.content
return true
end
end
return false
end
-- Using authentication
local function auth_example(task)
rspamd_http.request({
task = task,
url = "https://example.com/api/protected",
method = "GET",
user = "username",
password = "secret",
callback = function(err, code, body, headers)
-- Process authenticated response
end
})
end
-- Using HTTPS with SSL options
local function https_example(task)
rspamd_http.request({
task = task,
url = "https://example.com/api/secure",
method = "GET",
no_ssl_verify = false, -- Verify SSL (default)
callback = function(err, code, body, headers)
-- Process secure response
end
})
end
-- Using keep-alive and gzip
local function advanced_example(task)
rspamd_http.request({
task = task,
url = "http://example.com/api/data",
method = "POST",
body = task:get_content(),
gzip = true, -- Compress request body
keepalive = true, -- Use keep-alive connection
max_size = 1024 * 1024, -- Limit response to 1MB
callback = function(err, code, body, headers)
-- Process response
end
})
end
Brief content:
Functions:
Function | Description |
---|---|
rspamd_http.request({params...}) | This function creates HTTP request and accepts several parameters as a table using key=value syntax. |
Functions
The module rspamd_http
defines the following functions.
Function rspamd_http.request({params...})
This function creates HTTP request and accepts several parameters as a table using key=value syntax. Required params are:
url
task
In taskless mode, instead of task
required are:
ev_base
config
Parameters:
url {string}
: specifies URL for a request in the standard URI form (e.g. 'http://example.com/path')callback {function}
: specifies callback function in formatfunction (err_message, code, body, headers)
that is called on HTTP request completion. if this parameter is missing, the function performs "pseudo-synchronous" call (see Synchronous and Asynchronous API overviewtask {task}
: if called from symbol handler it is generally a good idea to use the common task objects: event base, DNS resolver and events sessionheaders {table}
: optional headers in form[name='value']
or[name=['value1', 'value2']]
to duplicate a header with multiple valuesmime_type {string}
: MIME type of the HTTP content (for example,text/html
)body {string/text}
: full body content, can be opaquerspamd{text}
to avoid data copyingtimeout {number}
: floating point request timeout value in seconds (default is 5.0 seconds)resolver {resolver}
: to perform DNS-requests. Usually got from eithertask
orconfig
gzip {boolean}
: if true, body of the requests will be compressedno_ssl_verify {boolean}
: disable SSL peer checkskeepalive {boolean}
: enable keep-alive pooluser {string}
: for HTTP authenticationpassword {string}
: for HTTP authentication, only if "user" present
Returns:
{boolean}
:true
, in async mode, if a request has been successfully scheduled. If this value isfalse
then some error occurred, the callback thus will not be called.- In sync mode
string|nil, nil|table
In sync mode error message if any and response as table:int
code,string
content andtable
headers (header -> value)
Back to module description.
Back to top.