Module rspamd_upstream_list

This module implements upstreams manipulation from LUA API. This functionality can be used for load balancing using different strategies including:

• round-robin: balance upstreams one by one selecting accordingly to their weight
• hash: use stable hashing algorithm to distribute values according to some static strings
• master-slave: always prefer upstream with higher priority unless it is not available

Here is an example of upstreams manipulations:

Example:

local rspamd_logger = require "rspamd_logger"
local rspamd_redis = require "rspamd_redis"
local upstream_list = require "rspamd_upstream_list"
local upstreams = upstream_list.create('127.0.0.1,10.0.0.1,10.0.0.2', 6379)

local function sym_callback(task)
	local upstream = upstreams:get_upstream_by_hash(task:get_from()[1]['domain'])

	local function cb(task, err, data)
		if err then
			upstream:fail()
		else
			upstream:ok()
		end
	end

	local addr = upstream:get_addr()
	rspamd_redis.make_request(task, addr, cb,
		'PUSH', {'key', 'value'})
end

Brief content:

Functions:

Methods:

Functions

The module rspamd_upstream_list defines the following functions.

Function upstream_list.create(cfg, def, [default_port])

Create new upstream list from its string definition in form <upstream>,<upstream>;<upstream>

Parameters:

• cfg {rspamd_config}: configuration reference
• def {string}: upstream list definition
• default_port {number}: default port for upstreams

Returns:

• {upstream_list}: upstream list structure

Back to module description.

Methods

The module rspamd_upstream_list defines the following methods.

Method upstream:get_addr()

Get ip of upstream

Parameters:

No parameters

Returns:

• {ip}: ip address object

Back to module description.

Method upstream:get_name()

Get name of upstream

Parameters:

No parameters

Returns:

• {string}: name of the upstream

Back to module description.

Method upstream:get_port()

Get port of upstream

Parameters:

No parameters

Returns:

• {int}: port of the upstream

Back to module description.

Method upstream:fail()

Indicate upstream failure. After certain amount of failures during specified time frame, an upstream is marked as down and does not participate in rotations.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method upstream:ok()

Indicates upstream success. Resets errors count for an upstream.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method upstream_list:get_upstream_by_hash(key)

Get upstream by hash from key

Parameters:

• key {string}: a string used as input for stable hash algorithm

Returns:

• {upstream}: upstream from a list corresponding to the given key

Back to module description.

Method upstream_list:get_upstream_round_robin()

Get upstream round robin (by current weight)

Parameters:

No parameters

Returns:

• {upstream}: upstream from a list in round-robin matter

Back to module description.

Method upstream_list:get_upstream_master_slave()

Get upstream master slave order (by static priority)

Parameters:

No parameters

Returns:

• {upstream}: upstream from a list in master-slave order

Back to module description.

Method upstream_list:all_upstreams()

Returns all upstreams for this list

Parameters:

No parameters

Returns:

• {table|upstream}: all upstreams defined

Back to module description.

Method upstream_list:add_watcher(what, cb)

Add new watcher to the upstream lists events (table or a string):

• success - called whenever upstream successfully used
• failure - called on upstream error
• online - called when upstream is being taken online from offline
• offline - called when upstream is being taken offline from online Callback is a function: function(what, upstream, cur_errors) … end

Parameters:

No parameters

Returns:

• nothing

Example:

ups:add_watcher('success', function(what, up, cur_errors) ... end)
ups:add_watcher({'online', 'offline'}, function(what, up, cur_errors) ... end)

Back to module description.

Back to top.