Utils

Description

vmod_utils is a VMOD for useful functions that don’t require their own VMOD.

Functions

bitwise operations

INT bitwise_and(INT a, INT b)

INT bitwise_or(INT a, INT b)

INT bitwise_xor(INT a, INT b)

• Return value

  The result of the corresponding operation (&, |, ^).

dyn_probe

OBJECT dyn_probe([STRING url], [STRING request], [BOOL tcponly], [INT expected_response], [DURATION timeout], [DURATION interval], [INT initial], [INT window], [INT threshold])

• Description

  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. Dynamic probes are used by dynamic backends to provide the flexibility that these backends require.

• Return Value

  An object with the .probe() method.

probe

PROBE .probe()

• Return Value

  The probe specified during the creation of the object.

• VCL example

  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());
  }
  

newline

STRING newline()

• Description

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

• Return Value

  The newline escape sequence, \n.

time_format

STRING time_format(STRING format, BOOL local_time, [TIME time])

• Description

  Format the time according to format. This is an interface for strftime.

• Return Value

  The formated time as a string.

  • format

    The format that the time should be in. For more information about possible options see the man page for strftime.

  • local_time

    Should the time be in the local time zone or GMT. Defaults to GMT.

  • time

    An optional parameter of a time to format. Defaults to the current time.

fast_304

VOID fast_304()

• Description

  Perform a fast 304 cache insert. New or changed headers will not be updated into cache. The object currently in cache will simply have its TTL extended. This reduces the cache read/write overhead of a 304 response to zero. Can only be used in vcl_backend_response. If used on a non 304 response, it is ignored.

• Return Value

  None

vcl_name

STRING vcl_name()

• Return Value

  The name of the current VCL.

mod

INT mod(INT a, INT b)

• Description

  Return the result of the modulus operation between a and b (a mod b). An error is triggered if b is 0. If a or b is negative, the output may be negative.

• Return Value

  The result of a mod b. This is the remained of a divided by b.

  • a

    The quotient of the division.

  • b

    The divisior of the division.

fast_random

REAL fast_random(REAL lo, REAL hi)

• Description

  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.

• Return

  A pseudo random real number between lo and hi.

  • lo

    The lower bound of possible return values.

  • hi

    The upper bound of possible return values.

fast_random_int

INT fast_random_int (INT m)

• Description

  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.

• Return

  A quasi random integer between 0 and m-1 (inclusive).

  • m

    If positive, one higher than the upper bound of possible return values. If 0 or negative, The value is ignored.

resolve_backend

BACKEND resolve_backend([BACKEND be])

• Description

  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.

• Return

  Either a backend or NULL if none is available.

waitinglist

BOOL waitinglist()

• Description

  Indicate if there are clients on this object’s waitinglist.

• Return

  True if there are other clients waiting for this object. Otherwise return false.

backend_misses

INT backend_misses()

• Description

  How many times an uncacheable object has been looked up within a given ttl. Can only be called in backend subroutines.

• Return

  The number of times an uncachable object has been looked up.

• VCL example

  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;
      }
  }