vmod_var.vcc

$Module var 3 "Variable support for Varnish VCL"

This VMOD implements basic variable support in VCL.

It supports strings, integers, real numbers, durations, IP addresses
and backends. There are methods to get and set each data type.

Global variables have a lifespan that extends across requests and
VCLs, for as long as the vmod is loaded. Global variables only support
strings.

The remaining functions have PRIV_TASK lifespan and are local to a single
request or backend request.

.. vcl-start

Example::

    vcl 4.0;
    import var;

    backend default { .host = "192.0.2.11"; .port = "8080"; }

    sub vcl_recv {
        # Set and get some values.
        var.set("foo", "bar");
        set req.http.x-foo = var.get("foo");

        var.set_int("ten", 10);
        var.set_int("five", 5);
        set req.http.twenty = var.get_int("ten") + var.get_int("five") + 5;

        # VCL will use the first token to decide final data type. Headers are strings.
        # set req.http.X-lifetime = var.get_int("ten") + " seconds"; #  Won't work.
        set req.http.X-lifetime = "" + var.get_int("ten") + " seconds";  # Works!

        var.set_duration("timedelta", 1m);  # 60s
        set req.http.d1 = var.get_duration("timedelta");

        var.set_ip("endpoint", client.ip);
        set req.http.x-client = var.get_ip("endpoint");

        # Unset all non-global variables.
        var.clear();

        # Demonstrate use of global variables as state flags.
        if (req.url ~ "/close$") {
            var.global_set("open", "no");
        }
        else if (req.url ~ "/open$") {
            var.global_set("open", "yes");
        }

        if (var.global_get("open") != "yes") {
            return (synth(200, "We are currently closed, sorry!"));
        }
    }

.. vcl-end


$ABI vrt
$Function VOID set(PRIV_TASK, STRING key, STRING value)

Set `key` to `value`.

$Function STRING get(PRIV_TASK, STRING )

Get `key` with data type STRING. If stored `key` is not a STRING a NULL string is returned.

$Function VOID global_set(STRING, STRING)

$Function STRING global_get(STRING)

$Function VOID set_int(PRIV_TASK, STRING key, INT value)

Set `key` to `value`.

$Function INT get_int(PRIV_TASK, STRING key)

Get `key` with data type INT. If stored `key` is not an INT zero will be returned.

$Function VOID set_string(PRIV_TASK, STRING key, STRING value)

Identical to set().

$Function STRING get_string(PRIV_TASK, STRING key)

Identical to get().

$Function VOID set_real(PRIV_TASK, STRING key, REAL value)

Set `key` to `value`.

$Function REAL get_real(PRIV_TASK, STRING key)

Get `key` with data type REAL. If stored `key` is not a REAL zero will be returned.

$Function VOID set_duration(PRIV_TASK, STRING key, DURATION value)

Set `key` to `value`.

$Function DURATION get_duration(PRIV_TASK, STRING key)

Get `key` with data type DURATION. If stored `key` is not a DURATION zero will be returned.

$Function VOID set_ip(PRIV_TASK, STRING key, IP value)

Set `key` to `value`.

$Function IP get_ip(PRIV_TASK, STRING key)

Get `key` with data type IP. If stored `key` is not an IP null will be returned.

$Function VOID set_backend(PRIV_TASK, STRING key, BACKEND value)

Set `key` to `value`.

$Function BACKEND get_backend(PRIV_TASK, STRING key)

Get `key` with data type BACKEND. If stored `key` is not a BACKEND,
null will be returned.

$Function VOID clear(PRIV_TASK)

Clear all non-global variables.