Search
Varnish Enterprise

Utils

Description

The utils vmod is a VMOD for useful functions that don’t require their own VMOD.

API

newline

STRING newline()

Return a string consisting of a newline escape sequence, \n.

Arguments: None

Type: Function

Returns: String

time_format

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

fast_304

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

is_fast_304

BOOL is_fast_304()

Was a fast 304 performed.

Arguments: None

Type: Function

Returns: Bool

was_max_conn

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

vcl_name

STRING vcl_name()

The name of the current VCL.

Arguments: None

Type: Function

Returns: String

dyn_probe

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 .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

mod

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

fast_random

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

fast_random_int

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 INT

Type: Function

Returns: Int

vcp_vfp_reset

VOID vcp_vfp_reset()

Clear out any configured VDP VFPs

Arguments: None

Type: Function

Returns: None

bitwise_and

INT bitwise_and(INT a, INT b)

Performs bitwise and operation.

Arguments:

  • a accepts type INT

  • b accepts type INT

Type: Function

Returns: Int

bitwise_or

INT bitwise_or(INT a, INT b)

Performs bitwise or operation.

Arguments:

  • a accepts type INT

  • b accepts type INT

Type: Function

Returns: Int

bitwise_xor

INT bitwise_xor(INT a, INT b)

Performs bitwise xor operation.

Arguments:

  • a accepts type INT

  • b accepts type INT

Type: Function

Returns: Int

bytes2string

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

resolve_backend

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 BACKEND

Type: Function

Returns: Backend

backend_misses

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

waitinglist

BOOL waitinglist()

Return true if there are clients on this object’s waitinglist.

Arguments: None

Type: Function

Returns: Bool

hash_ignore_vary

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

base64_encode

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

cpu_id

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

numa_node_id

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

force_fresh

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

set_pipe_timeout

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 DURATION

Type: Function

Returns: None

apply_cache_headers

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

hex2integer

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

lookup_file

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 STRING

Type: Function

Returns: String

Availability

The utils VMOD is available in Varnish Enterprise version 6.0.3r7 and later.