#-
# This document is copyright and licensed under the same conditions as
# the libvmod-weightadjust project. See LICENSE for details.

$Module weightadjust 3 Weightadjust VMOD

DESCRIPTION
===========

$Event event_function

$Object random(PRIV_VCL)

Description
	Create a random backend director.

	The random director distributes load over the backends using
	a weighted random probability distribution.
	The "testable" random generator in varnishd is used, which
	enables deterministic tests to be run (See: d00004.vtc).

Example::

	new vdir = directors.random();

$Method VOID .add_backend(BACKEND backend, REAL weight,
			  STRING weight_update=0,
			  STRING url="/",
			  STRING request=0,
			  DURATION timeout=2,
			  DURATION interval=5,
			  INT buffer=4096)

Description
	Add a *backend* to the director with a given initial *weight*.

	Each backend will receive approximately 100 * (weight /
	(sum(all_added_weights))) per cent of the traffic sent to this
	director.

	If a regular expression *weight_update* is given, the weight
	assigned to this backend is updated by a HTTP1 request defined
	by either *url* or the string *request*, the latter having
	precedence if given.

	The *weight_update* regular expression needs to contain
	exactly one subexpression to capture a real value in C locale
	format (ddd.ddd). The match is ran against the first *buffer*
	bytes of the HTTP response, headers and body in multiline mode
	(``^`` matches start of line, ``$`` matches end of line or end buffer).

	The interval to issue weight update requests is defined by the
	*interval* parameter, the timeout both for sending and
	receiving all of the request and response, respectively, is
	deined by *timeout*. Note that the actual interval can be
	longer than specified if the combined request and response
	time exceeds it.

	The *buffer* parameter defines a maximum size for the http
	response (headers and body) to scan with the *weight_update*
	regular expression.

Example::

	vdir.add_backend(backend1, 10.0,
			 "^X-Weight: *(\d+\.\d+)", "/get-weight.php")
	vdir.add_backend(backend2,  2.0,
			 "^X-Weight: *(\d+\.\d+)", "/get-weight.php")

$Method VOID .remove_backend(BACKEND backend)

Description
	Remove a backend from the director.

Example::
	vdir.remove_backend(backend1);
	vdir.remove_backend(backend2);

$Method BACKEND .backend()

Description
	Pick a backend from the director.
Example
	set req.backend_hint = vdir.backend();