The utils
vmod is a VMOD for useful functions that don’t require their own VMOD.
STRING newline()
Return a string consisting of a newline escape sequence, \n
.
Arguments: None
Type: Function
Returns: String
STRING time_format(STRING format, BOOL local_time = 0, [TIME time])
Format the time according to format
. This is an interface for strftime
.
Arguments:
format
accepts type STRING
local_time
accepts type BOOL with a default value of 0
optional
time
accepts type TIME
Type: Function
Returns: String
VOID fast_304()
Perform a fast 304 insert. This revalidates the stale objects instead of performing the HTTP standard’s complicated rules (see https://httpwg.org/specs/rfc7232.html#status.304 and https://httpwg.org/specs/rfc7234.html#freshening.responses) for calculating new headers.
When fast_304()
is not used, the standard requires Varnish to create a new object with new headers, where most use cases are better off with simply revalidating the existing objects.
A fast_304
will conduct a simple book update, whereas a normal 304 will perform a full copy of the object payload. For big objects, this represents a potentially very significant reduction in IO cost and it is strongly recommended to use fast_304
when using MSE.
Arguments: None
Type: Function
Returns: None
BOOL is_fast_304()
Was a fast 304 performed.
Arguments: None
Type: Function
Returns: Bool
BOOL was_max_conn()
This function can only be called in sub vcl_backend_error
. Returns true
if the reason that we are in sub vcl_backend_error
is, in fact, that the selected backend’s maximum connections was reached when a new connection was requested.
Arguments: None
Type: Function
Returns: Bool
STRING vcl_name()
The name of the current VCL.
Arguments: None
Type: Function
Returns: String
OBJECT dyn_probe([STRING url], [STRING request], [BOOL tcponly], [INT expected_response], [DURATION timeout], [DURATION interval], [INT initial], [INT window], [INT threshold])
Build an object that is able to output a probe. The argument list is the same as for the static VCL declaration of a probe, with the same restrictions. This allows to generate probes in vcl_init, notably using dynamic values. These dynamic probes are then used by dynamic backends.
Arguments:
url
accepts type STRING
request
accepts type STRING
tcponly
accepts type BOOL
expected_response
accepts type INT
timeout
accepts type DURATION
interval
accepts type DURATION
initial
accepts type INT
window
accepts type INT
threshold
accepts type INT
Type: Object
Returns: Object.
PROBE .probe()
The probe specified during the creation of the object.
import utils;
import goto;
sub vcl_init {
#get the probe URL from an env variable
new dyn_probe = utils.dyn_probe(sdt.getenv("PROBE_URL"));
# create a dynamic backend with above probe
new goto_dir = goto.dns_director("foo.example.com", probe= dyn_probe.probe());
}
Arguments: None
Type: Method
Returns: Probe
INT mod(INT a, INT b)
Return the result of a mod b
, or triggers an error if b
is 0. Be
aware that if a
or b
is negative, the output may be negative.
Arguments:
a
accepts type INT
b
accepts type INT
Type: Function
Returns: Int
REAL fast_random(REAL lo, REAL hi)
Returns a pseudo random real number between lo and hi. This is a drop-in replacement for std.random(), but with a much higher focus on speed. Like std.random(), this should not be used for cryptographical applications.
set beresp.http.random-number = utils.fast_random(1, 100);
Arguments:
lo
accepts type REAL
hi
accepts type REAL
Type: Function
Returns: Real
INT fast_random_int(INT m)
When m is a positive number, returns a quasi random integer between 0 and m-1 (inclusive). If m is zero or negative, a random INT is returned, which can be either positive or negative.
set beresp.http.random-int = 1 + utils.fast_random_int(3);
After the above, the header random-int will be “1”, “2” or “3”.
Arguments:
m
accepts type INTType: Function
Returns: Int
VOID vcp_vfp_reset()
Clear out any configured VDP VFPs
Arguments: None
Type: Function
Returns: None
INT bitwise_and(INT a, INT b)
Performs bitwise and
operation.
Arguments:
a
accepts type INT
b
accepts type INT
Type: Function
Returns: Int
INT bitwise_or(INT a, INT b)
Performs bitwise or
operation.
Arguments:
a
accepts type INT
b
accepts type INT
Type: Function
Returns: Int
INT bitwise_xor(INT a, INT b)
Performs bitwise xor
operation.
Arguments:
a
accepts type INT
b
accepts type INT
Type: Function
Returns: Int
STRING bytes2string(BYTES b, ENUM {B, KB, MB, GB, TB} unit = B)
Converts the bytes b to string. unit determines the unit the converted string should be.
set req.http.size = utils.bytes2string(10000KB, GB);
Arguments:
b
accepts type BYTES
unit
is an ENUM that accepts values of B
, KB
, MB
, GB
, and TB
with a default value of B
optional
Type: Function
Returns: String
BACKEND resolve_backend([BACKEND be])
Resolve the effective backend from bereq.backend
, or the supplied
argument be
if present. Only directors can resolve to a different
backend, and only from a backend subroutine.
Arguments:
be
accepts type BACKENDType: Function
Returns: Backend
INT backend_misses()
How many times an uncacheable object has been looked up within the ttl. Can only be called in backend subroutines.
Insert an object on the second miss. This reduces expensive cache churn on long tail content.
import utils;
sub vcl_backend_response {
if (!utils.waitinglist() && utils.backend_misses() == 0) {
set beresp.uncacheable = true;
set beresp.ttl = 24h;
}
}
Arguments: None
Type: Function
Returns: Int
BOOL waitinglist()
Return true if there are clients on this object’s waitinglist.
Arguments: None
Type: Function
Returns: Bool
VOID hash_ignore_vary(BOOL flag = 1)
Set the flag to disable vary header checks during lookup. When the flag is omitted, variants are ignored. Proceed with caution, ignoring vary headers could lead to inconsistent deliveries and depending on how they are used by the origin server, security vulnerabilities. When in doubt, don’t use it.
DEPRECATED: use the req.hash_ignore_vary
flag directly.
Arguments:
flag
accepts type BOOL with a default value of 1
optional
Type: Function
Returns: None
VOID base64_encode(ENUM {STD, URL} alphabet = STD, BOOL pad = 1, BYTES buffer_size = 32768)
Arguments:
pad
accepts type BOOL with a default value of 1
optional
buffer_size
accepts type BYTES with a default value of 32768
optional
alphabet
is an ENUM that accepts values of STD
, and URL
with a default value of STD
optional
Type: Function
Returns: None
INT cpu_id()
Returns the current CPU id. For older operating systems not running
on an x86_64 CPU where the C lib does not provide getcpu
, this function will return 0.
Arguments: None
Type: Function
Returns: Int
INT numa_node_id()
Returns the current NUMA node id. If NUMA is not present, it will always return zero.
For older operating systems not running on an x86_64 CPU where the C lib does not
provide getcpu
, this function will return 0.
Arguments: None
Type: Function
Returns: Int
BOOL force_fresh(BOOL flag = 1)
Force the subsequent backend fetch to happen on a fresh connection,
not on a reused backend connection. This function can only be called
from a backend context (ie. sub vcl_backend_*
), for example from sub vcl_backend_fetch
.
Setting the flag to 0 turns off the flag, which allows you to take back the previous decision about forcing a fresh connection on the next retry.
Arguments:
flag
accepts type BOOL with a default value of 1
optional
Type: Function
Returns: Bool
VOID set_pipe_timeout(DURATION timeout)
Set the pipe idle timeout. The timeout will be set for the current session only, and will silently fail if the session is not available in the current VCL sub.
Arguments:
timeout
accepts type DURATIONType: Function
Returns: None
VOID apply_cache_headers()
Description
Parse the backend response headers and set TTL, grace and keep according
to them. Must be called from vcl_backend_response
.
Arguments: None
Type: Function
Returns: None
INT hex2integer(STRING hex, INT fallback)
Converts the hexadecimal number hex to an integer. The hexadecimal number must
start with 0x
and is case insensitive. If conversion fails, fallback will
be returned.
set req.http.integer = utils.hex2integer("0x6089F", 0);
set req.http.integer = utils.hex2integer("0x3bf8a9", 0);
Arguments:
hex
accepts type STRING
fallback
accepts type INT
Type: Function
Returns: Int
STRING lookup_file(STRING file)
Searches for file
in the vcl_path
used at VCL load time and returns its
absolute path.
Arguments:
file
accepts type STRINGType: Function
Returns: String
The utils
VMOD is available in Varnish Enterprise version 6.0.3r7
and later.