Version: Next

Module rspamd_upstream

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:

Function	Description
`upstream_list.create(cfg, def, [default_port])`	Create new upstream list from its string definition in form `<upstream>,<upstream>;<upstream>`.

Methods:

Method	Description
`upstream:get_addr()`	Get ip of upstream.
`upstream:get_name()`	Get name of upstream.
`upstream:get_port()`	Get port of upstream.
`upstream:fail()`	Indicate upstream failure.
`upstream:ok()`	Indicates upstream success.
`upstream_list:get_upstream_by_hash(key)`	Get upstream by hash from key.
`upstream_list:get_upstream_round_robin()`	Get upstream round robin (by current weight).
`upstream_list:get_upstream_master_slave()`	Get upstream master slave order (by static priority).
`upstream_list:all_upstreams()`	Returns all upstreams for this list.
`upstream_list:add_watcher(what, cb)`	Add new watcher to the upstream lists events (table or a string).

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.