diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2015-02-14 11:55:18 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2015-02-14 11:55:18 +0200 |
commit | 86be1ec2e77f2d04ef1036e91a9987795884d282 (patch) | |
tree | 495bf6874bd239eb7047a8ce8477dcc9b980bc1f /README | |
parent | a7df6c9f56d96fa1e1c1a5cb67ef951560181984 (diff) | |
download | vmod-variable-86be1ec2e77f2d04ef1036e91a9987795884d282.tar.gz vmod-variable-86be1ec2e77f2d04ef1036e91a9987795884d282.tar.bz2 |
Add README and NEWS files.
Diffstat (limited to 'README')
-rw-r--r-- | README | 222 |
1 files changed, 222 insertions, 0 deletions
@@ -0,0 +1,222 @@ +Vmod-variable README +Copyright (C) 2015 Sergey Poznyakoff +See the end of file for copying conditions. + +* Introduction + +This file contains brief information about configuring, testing +and using vmod-variable. It is *not* intended as a replacement +for the documentation, and is provided as a brief reference only. +For accessing complete vmod-variable documentation, see the section +'Documentation' below. + +For a list of differences between this module and vmod_var, see +the section "vmod_variable vs. vmod_var". + +* Overview + +This module provides extended variable support for VCL scripts. +It compiles for Varnish versions 3 and 4. + +There are two kinds of variables: session-specific, which have the +lifespan of one HTTP session (connection) and cease to exist when +it is closed, and global, which are shared between all sessions. + +Session-specific variables are typed, a pair of functions is provided +for setting and retrieveng variables od a particular type. For +example the function set_duration sets a duration variable, and +get_duration retrieves its value: + + set beresp.ttl = variable.get_int("ttl"); + +Special functions are provided for testing if a variable is defined: +the defined() function returns true if the variable is defined, and +the type_of() function returns the type of the variable. + +A special fearure of this module are regset() and queryset() +functions. The regset() function allows you to parse a string +(e.g. a URL or header value) according to a regular expression +and to set several variables at once to selected substrings of +the input string, optionally converting between different types. +For example, the fragment below sets 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"); + +The first argument to regset declares a list of variables to be +set, along with their types (":d" standing for "duration") and +values to be assigned (after = signs). The latter use backreferenses +to refer to the substrings captured by the regular expression and add +the "s" suffix to each captured string to obtain a valid duration. + +To obtain the same effect without variable.regset, one would have to +use regsub twice, casting the result explicitly + + set beresp.ttl = std.duration(regsub(beresp.http.Surrogate-Control, + "^(?:.*,)?max-age=([0-9]+)(?:+([0-9]+))", + "\1s")); + set beresp.grace = std.duration(regsub(beresp.http.Surrogate-Control, + "^(?:.*,)?max-age=([0-9]+)(?:+([0-9]+))", + "\2s")); + +The queryset() function treats its argument as a HTTP query, and +defines variables according to it. For example: + + variable.queryset("q:s,n:i,p:i", regsub(req.url, ".*\?(.+)", "\1")); + +If req.url contained "q=term&n=10&p=5", this call will define three +variables: a string variable "q" having the value "term", and two +integer variables "n" and "p" with the values 10 and 5 +correspondingly. + +* Functions + +** Typed accessors: + +VOID set(STRING name, STRING value) +VOID set_string(STRING name, STRING name) + Define a string variable + +STRING get(STRING name) +STRING get_string(STRING name) + Retrieve the value of a string variable + +VOID set_int(STRING name, INT value) + Define an integer variable +INT get_int(STRING name) + Retrieve the value of an integer variable + +VOID set_real(STRING name, REAL value) + Define a floating-point variable +REAL get_real(STRING name) + Retrieve the value of a floating-point variable + +VOID set_duration(STRING name, DURATION value) + Define a duration variable +DURATION get_duration(STRING name) + Retrieve the value of a duration variable + +VOID unset(STRING name) + Unset the variable + +VOID clear() + Unset all variables + +** Testing for existence + +BOOL defined(STRING name) + Test if the variable is defined + +STRING type_of(STRING name) + Return type of the variable (one of: UNSET, STRING, INT, + REAL, DURATION) + +** Special functions + +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 decla- + rations, each one having the syntax NAME[:TYPE][=VALUE] (brackets + denoting optional parts). The :TYPE suffix declares the type + of the variable (STRING, INT, REAL, DURATION). The =VALUE part + defines its value. It can refer to the nine captured + substrings via the usual notation \1 through \9. + +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. + +** Global variables + +VOID global_set(STRING name, STRING value) + Set a global variable +STRING global_get(STRING name) + Retrieve the value of a global variable +BOOL global_defined(STRING name) + Test whether the global variable is defined +VOID global_unset(STRING name) + Unset a global variable +VOID global_clear() + Unset all global variables + +* vmod_variable vs. vmod_var + +This module is backward-compatibile with vmod_var. To facilitate +transition, it uses the same naming scheme, so switching to use +vmod_variable in your VCL script is just a matter of replacing +s/var\./variable./ + +Main differences of vmod_variable from vmod_var: + +1. Both Varsnish 3 and 4 are supported; + +2. Variables are stored in hash tables with open addressing, to +speed up accesses (vmod_var keeps them in singly-linked lists). + +3. Functions for testing existence and types of variables, and for +unsetting a variable: defined(), type_of() and unset() + +4. The regset() and queryset() functions; + +5. Additional functions for global variables: global_clear(), +global_defined() and global_unset(). + +* Installation + +In order to compile the package you need to have a configured and +compiled Varnish source tree. Both Varnish 3 and 4 are OK. + +Supposing that the varnish source tree is available under +/usr/src/varnish-4.0.2, run: + + ./configure --with-varnish-source=/usr/src/varnish-4.0.2 + +The `--with-varnish-source' option is mandatory: it tells configure +where Varnish sources reside. + +Once configured, do + + make + +This will build the module. After this step you can optionally run +'make test' to test the package. + +Finally, run the following command as root: + + make install + +* Documentation + +The manual page vmod-variable(3) will be available after a successful +install. To read it without actually installing the module, run +`man src/vmod-variable.3'. + +An online copy of the documentation is available from +http://www.gnu.org.ua/software/vmod-variable. + +* Bug reporting + +Send bug reports and suggestions to <gray@gnu.org> + + +Local Variables: +mode: outline +paragraph-separate: "[ ]*$" +version-control: never +End: + |