Search
Varnish Cache Plus

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. For big objects, fast_304 represents a potentially very significant reduction of cost.

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

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.

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.

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.

Arguments:

  • flag accepts type BOOL with a default value of 1 optional

Type: Function

Returns: Bool

Availability

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