Skip to main content

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:

FunctionDescription
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 format function (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 overview
  • task {task}: if called from symbol handler it is generally a good idea to use the common task objects: event base, DNS resolver and events session
  • headers {table}: optional headers in form [name='value'] or [name=['value1', 'value2']] to duplicate a header with multiple values
  • mime_type {string}: MIME type of the HTTP content (for example, text/html)
  • body {string/text}: full body content, can be opaque rspamd{text} to avoid data copying
  • timeout {number}: floating point request timeout value in seconds (default is 5.0 seconds)
  • resolver {resolver}: to perform DNS-requests. Usually got from either task or config
  • gzip {boolean}: if true, body of the requests will be compressed
  • no_ssl_verify {boolean}: disable SSL peer checks
  • keepalive {boolean}: enable keep-alive pool
  • user {string}: for HTTP authentication
  • password {string}: for HTTP authentication, only if "user" present

Returns:

  • {boolean}: true, in async mode, if a request has been successfully scheduled. If this value is false 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 and table headers (header -> value)

Back to module description.

Back to top.