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 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.