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.

Back to top.