VMOD-VARIABLE(1)

NAME
vmod-variable - variable support for Varnish Cache

SYNOPSIS
import variable [PATH];

DESCRIPTION
This module provides enhanced variable support for VCL scripts.

There are two kind of variables: session-specific and global. Session-specific variables have a lifespan of one HTTP session and cease to exist when it is closed. Such variables can be of almost any VCL type: STRING, INT, REAL, or DURATION. For each of these types a pair of functions is provided for setting the variable and obtaining its value.

Two functions are provided for setting several variables at once. The regset function parses its input according to a regular expression and sets variables to the captured strings, using sophisticated declaration patterns.

The queryset function parses its input as a HTTP query string and sets the variables defined in it.

The global variables are shared between all threads and sessions. They can hold only string values.

VMOD_VARIABLE VS. VMOD_VAR
This module doesn't share any code with vmod_var. Compared with the latter, it provides the following new features:

.   Both Varnish 3 and 4 are supported;

.   Variables are stored in hash tables with open addressing, to speed up accesses (vmod_var keeps them in singly-linked lists).

.   Functions for testing existence and types of variables, and for unsetting a variable: defined(), type_of(), and unset().

.   The regset() and queryset() functions.

.   Additional functions for global variables: global_clear(), global_defined(), and global_unset().

To facilitate transition, vmod_variable uses the same naming scheme as vmod_var, so switching to using it in your VCL script is as simple as replacing s/var\./variable./.

FUNCTIONS
The function below operate on session-local variables.

VOID set(STRING name, STRING value)
    Assigns value to the string variable name.

STRING get(STRING name)
    Returns value of the string variable name. If the variable is not defined, NULL is returned.

VOID set_int(STRING name, INT value)
    Assigns value to the integer variable name.

INT get_int(STRING name)
    Returns value of the integer variable name. If the variable is not defined, 0 is returned.

VOID set_string(STRING name, STRING value)
    Same as set.

STRING get_string(STRING name)
    Same as get.

VOID set_real(STRING name, REAL value)
    Assigns value to the floating-point variable name.

REAL get_real(STRING name)
    Returns value of the floating-point variable name. If the variable is not defined, 0.000 is returned.

VOID set_duration(STRING name, DURATION value)
    Assigns value to the duration variable name.

DURATION get_duration(STRING name)
    Returns value of the duration variable name. If the variable is not defined, 0.000 is returned.

VOID regset(STRING vardcl, STRING regex, STRING input)
    If input matches regular expression regex, initializes variables declared in vardcl to parts of input captured by parenthesized groups in regex. The parameter vardcl contains one or more comma-separated declarations. Each declaration is a variable name, optionally followed by the following constructs, in that order: :TYPE and =REPL. The :TYPE construct declares the type of the variable. TYPE can be one of STRING, INT, REAL, DURATION, or any abbreviation of these (case-insensitive). E.g. x:r means that the variable x is of REAL type. If this part is omitted, STRING type is assumed. The =REPL suffix instructs the function to set the variable to the value computed according to REPL, which is a replacement expression in the sense of regsub. If this part is omitted, the variable is initialized to the value of the Nth capture group from regex, where N is the position of that declaration in vardcl. Both parts can be used together, for example: time:d=\1m will set the time variable to the duration obtained by concatenating first captured group with the suffix m. Backreferences referring to unexisting capturing groups are retained verbatim.

VOID queryset(STRING vardcl, STRING input)
    Parses input as HTTP query string and assigns variables according to vardcl. If vardcl is empty, the function will define all variables present in input to string values. Otherwies, only the named variables will be set. The value of the vardcl variable is a comma-separated list of variable names, optionally followed by :TYPE construct, whose meaning is the same as in regset.

VOID clear()
    Re-initializes session-local variable table. All variables are forgotten.

BOOL defined(STRING name)
    Returns TRUE if the variable name is defined.

STRING type_of(STRING name)
    Returns type of the variable name. Available types are: UNSET, STRING, INT, REAL, DURATION.

VOID unset(STRING name)
    Unsets the variable name.

  Global variables

The functions below operate on global variables. Global variables can be hold only string values.

VOID global_set(STRING name, STRING value)
    Assigns value to the global variable name.

STRING global_get(STRING name)
    Returns value of the global variable name. If the variable is not defined, NULL is returned.

BOOL global_defined(STRING name)
    Returns TRUE if the global variable name is defined.

VOID global_unset(STRING name)
    Unsets global variable name.

VOID global_clear()
    Re-initializes global variable table. All variables are forgotten.

EXAMPLES

.
Set ttl and grace parameters of the object according to the
    Surrogate-Control header.

    variable.regset("ttl:d=\1s,grace:d=\2s",
                    "^(?:.*,)?*max-age=([0-9]+)(?:+([0-9]+))",
                    beresp.http.Surrogate-Control);
    set beresp.ttl = variable.get_duration("ttl");
    set beresp.grace = variable.get_duration("grace");

.
Set local variables from GET parameters.

    if (req.request == "GET") {
      variable.queryset("", regsub(req.url, ".*\?(.+)", "\1"));
    }

SEE ALSO
vcl(7), varnishd(1).

AUTHORS
Sergey Poznyakoff

BUG REPORTS
Report bugs to <gray@gnu.org>.

COPYRIGHT
Copyright © 2015 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.